Networking API v2.0

General API Overview

API guide

This section introduces readers to OpenStack Networking (v2) API, provides guidelines on how to use it, and describes common features available to users throughout all Networking APIs.

General information

The Networking API v2.0 is a RESTful HTTP service that uses all aspects of the HTTP protocol including methods, URIs, media types, response codes, and so on. Providers can use existing features of the protocol including caching, persistent connections, and content compression. For example, providers who employ a caching layer can respond with a 203 code instead of a 200 code when a request is served from the cache. Additionally, providers can offer support for conditional GET requests by using ETags, or they may send a redirect in response to a GET request. Create clients so that these differences are accounted for.

Authentication and authorization

The Networking API v2.0 uses the OpenStack Identity service as the default authentication service. When Keystone is enabled, users that submit requests to the OpenStack Networking service must provide an authentication token in X-Auth-Token request header. You obtain the token by authenticating to the Keystone endpoint.

When Keystone is enabled, the project_id attribute is not required in create requests because the project ID is derived from the authentication token.

NOTE: Currently the Networking API accepts the deprecated tenant_id attribute for the project ID for backward compatibility.

The default authorization settings allow only administrative users to create resources on behalf of a different project.

OpenStack Networking uses information received from Keystone to authorize user requests. OpenStack Networking handles the following types of authorization policies:

  • Operation-based policies specify access criteria for specific operations, possibly with fine-grained control over specific attributes.

  • Resource-based policies access a specific resource. Permissions might or might not be granted depending on the permissions configured for the resource. Currently available for only the network resource.

The actual authorization policies enforced in OpenStack Networking might vary from deployment to deployment.

Request and response formats

The Networking API v2.0 supports JSON data serialization request and response formats only.

Request format

The Networking API v2.0 only accepts requests with the JSON data serialization format. The Content-Type header is ignored.

Tenant and project attributes in requests

Starting with the Newton release of the Networking service, the Networking API accepts the project_id attribute in addition to the tenant_id attribute in requests. The tenant_id attribute is accepted for backward compatibility. If both the project_id and the tenant_id attribute are provided in the same request, their values must be identical.

To determine whether a Networking API v2.0 endpoint supports the project_id attribute in requests, check that the project-id API extension is enabled (see Extensions).

Response format

The Networking API v2.0 always responds with the JSON data serialization format. The Accept header is ignored.

Query extension A .json extension can be added to the request URI. For example, the .json extension in the following requests are equivalent:

  • GET publicURL/networks

  • GET publicURL/networks.json

Tenant and project attributes in responses

Starting with the Newton release of the Networking service, the Networking API returns a project_id attribute in responses, while still returning a tenant_id attribute for backward compatibility. The values will always be identical.

To determine whether a Networking API v2.0 endpoint returns the project_id attribute in responses, check that the project-id API extension is enabled (see Extensions).

Filtering and column selection

The Networking API v2.0 supports filtering based on all top level attributes of a resource. Filters are applicable to all list requests.

For example, the following request returns all networks named foobar:

GET /v2.0/networks?name=foobar

When you specify multiple filters using different fields, the Networking API v2.0 returns only objects that meet all filtering criteria. The operation applies an AND condition among different filter fields.

OpenStack Networking offers an OR mechanism for filters by repeating the field with the different OR criteria. For example, to find all networks named foobar OR bizbaz:

GET /v2.0/networks?name=foobar&name=bizbaz

ORs and ANDs can be combined. For example, if you want all networks with admin_state_up=True and shared=True and named foobar or bizbaz:

GET /v2.0/networks?name=foobar&name=bizbaz&admin_state_up=True&shared=True

List of resources is supported in GET requests. For example, if you want the information of two specific ports that id is port_id_A or port_id_B:

GET /v2.0/ports?id=port_id_A&id=port_id_B

It treats ID filters as list and return ports with those 2 IDs.

Starting from Rocky release, the Networking API might support filtering attributes with empty value. For example, the request below lists all ports that have device_id attribute with empty value (which are unbound ports).

GET /v2.0/ports?device_id=

To determine if this feature is supported, a user can check whether the empty-string-filtering extension API is available.

Starting from Rocky release, the Networking API will perform validation on filtering attributes if the API extension filter-validation is available. If an API request contains an unknown or unsupported parameter, the server will return a 400 response instead of silently ignoring the invalid input.

Fields

By default, OpenStack Networking returns all attributes for any show or list call. The Networking API v2.0 has a mechanism to limit the set of attributes returned. For example, return id.

You can use the fields query parameter to control the attributes returned from the Networking API v2.0.

For example, the following request returns only id and name for each network:

GET /v2.0/networks.json?fields=id&fields=name

Pagination

To reduce load on the service, list operations will return a maximum number of items at a time. To navigate the collection, the parameters limit, marker and page_reverse can be set in the URI. For example:

?limit=100&marker=1234&page_reverse=False

The marker parameter is the ID of the last item in the previous list. The limit parameter sets the page size. The page_reverse parameter sets the page direction. These parameters are optional. If the client requests a limit beyond the maximum limit configured by the deployment, the server returns the maximum limit number of items.

For convenience, list responses contain atom next links and previous links. The last page in the list requested with page_reverse=False will not contain next link, and the last page in the list requested with page_reverse=True will not contain previous link. The following examples illustrate two pages with three items. The first page was retrieved through:

GET http://127.0.0.1:9696/v2.0/networks.json?limit=2

Pagination is an optional feature of OpenStack Networking API, and it might be disabled. If pagination is disabled, the pagination parameters will be ignored and return all the items.

If a particular plug-in does not support pagination operations, and pagination is enabled, the Networking API v2.0 will emulate the pagination behavior so that users can expect the same behavior regardless of the particular plug-in running in the background.

To determine if pagination is supported, a user can check whether the ‘pagination’ extension API is available.

Example Network collection, first page: JSON request

GET /v2.0/networks.json?limit=2 HTTP/1.1
Host: 127.0.0.1:9696
Content-Type: application/json
Accept: application/json

Example Network collection, first page: JSON response

{
    "networks": [
        {
            "admin_state_up": true,
            "id": "396f12f8-521e-4b91-8e21-2e003500433a",
            "name": "net3",
            "provider:network_type": "vlan",
            "provider:physical_network": "physnet1",
            "provider:segmentation_id": 1002,
            "router:external": false,
            "shared": false,
            "status": "ACTIVE",
            "subnets": [],
            "tenant_id": "20bd52ff3e1b40039c312395b04683cf"
            "project_id": "20bd52ff3e1b40039c312395b04683cf"
        },
        {
            "admin_state_up": true,
            "id": "71c1e68c-171a-4aa2-aca5-50ea153a3718",
            "name": "net2",
            "provider:network_type": "vlan",
            "provider:physical_network": "physnet1",
            "provider:segmentation_id": 1001,
            "router:external": false,
            "shared": false,
            "status": "ACTIVE",
            "subnets": [],
            "tenant_id": "20bd52ff3e1b40039c312395b04683cf"
            "project_id": "20bd52ff3e1b40039c312395b04683cf"
        }
    ],
    "networks_links": [
        {
            "href": "http://127.0.0.1:9696/v2.0/networks.json?limit=2&marker=71c1e68c-171a-4aa2-aca5-50ea153a3718",
            "rel": "next"
        },
        {
            "href": "http://127.0.0.1:9696/v2.0/networks.json?limit=2&marker=396f12f8-521e-4b91-8e21-2e003500433a&page_reverse=True",
            "rel": "previous"
        }
    ]
}

The last page won’t show the next links

Example Network collection, last page: JSON request

GET /v2.0/networks.json?limit=2&marker=71c1e68c-171a-4aa2-aca5-50ea153a3718 HTTP/1.1
Host: 127.0.0.1:9696
Content-Type: application/json
Accept: application/json

Example Network collection, last page: JSON response

{
    "networks": [
        {
            "admin_state_up": true,
            "id": "b3680498-03da-4691-896f-ef9ee1d856a7",
            "name": "net1",
            "provider:network_type": "vlan",
            "provider:physical_network": "physnet1",
            "provider:segmentation_id": 1000,
            "router:external": false,
            "shared": false,
            "status": "ACTIVE",
            "subnets": [],
            "tenant_id": "c05140b3dc7c4555afff9fab6b58edc2"
            "project_id": "c05140b3dc7c4555afff9fab6b58edc2"
        }
    ],
    "networks_links": [
        {
            "href": "http://127.0.0.1:9696/v2.0/networks.json?limit=2&marker=b3680498-03da-4691-896f-ef9ee1d856a7&page_reverse=True",
            "rel": "previous"
        }
    ]
}

Sorting

You can use the sort_key and sort_dir parameters to sort the results of list operations. Currently sorting does not work with extended attributes of resource. The sort_key and sort_dir can be repeated, and the number of sort_key and sort_dir provided must be same. The sort_dir parameter indicates in which direction to sort. Acceptable values are asc (ascending) and desc (descending).

Sorting is optional feature of OpenStack Networking API, and it might be disabled. If sorting is disabled, the sorting parameters are ignored.

If a particular plug-in does not support sorting operations and sorting is enabled, the Networking API v2.0 emulates the sorting behavior so that users can expect the same behavior regardless of the particular plug-in that runs in the background.

To determine if sorting is supported, a user can check whether the ‘sorting’ extension API is available.

Starting from Rocky release, the Networking API performs validation on sorting attributes if the API extension sort-key-validation is available. If an API request contains an unknown or unsupported sort key, the server will return a 400 response instead of silently ignoring the invalid input.

Synchronous versus asynchronous plug-in behavior

The Networking API v2.0 presents a logical model of network connectivity consisting of networks, ports, and subnets. It is up to the OpenStack Networking plug-in to communicate with the underlying infrastructure to ensure packet forwarding is consistent with the logical model. A plug-in might perform these operations asynchronously.

When an API client modifies the logical model by issuing an HTTP POST, PUT, or DELETE request, the API call might return before the plug-in modifies underlying virtual and physical switching devices. However, an API client is guaranteed that all subsequent API calls properly reflect the changed logical model.

For example, if a client issues an HTTP PUT request to set the attachment for a port, there is no guarantee that packets sent by the interface named in the attachment are forwarded immediately when the HTTP call returns. However, it is guaranteed that a subsequent HTTP GET request to view the attachment on that port returns the new attachment value.

You can use the status attribute with the network and port resources to determine whether the OpenStack Networking plug-in has successfully completed the configuration of the resource.

Bulk-create

The Networking API v2.0 enables you to create several objects of the same type in the same API request. Bulk create operations use exactly the same API syntax as single create operations except that you specify a list of objects rather than a single object in the request body.

Bulk operations are always performed atomically, meaning that either all or none of the objects in the request body are created. If a particular plug-in does not support atomic operations, the Networking API v2.0 emulates the atomic behavior so that users can expect the same behavior regardless of the particular plug-in running in the background.

OpenStack Networking might be deployed without support for bulk operations and when the client attempts a bulk create operation, a 400 Bad request error is returned.

Extensions

The Networking API v2.0 is extensible.

The purpose of Networking API v2.0 extensions is to:

  • Introduce new features in the API without requiring a version change.

  • Introduce vendor-specific niche functionality.

  • Act as a proving ground for experimental functionalities that might be included in a future version of the API.

To programmatically determine which extensions are available, issue a GET request on the v2.0/extensions URI.

To query extensions individually by unique alias, issue a GET request on the /v2.0/extensions/*alias_name* URI. Use this method to easily determine if an extension is available. If the extension is not available, a 404 Not Found response is returned.

You can extend existing core API resources with new actions or extra attributes. Also, you can add new resources as extensions. Extensions usually have tags that prevent conflicts with other extensions that define attributes or resources with the same names, and with core resources and attributes. Because an extension might not be supported by all plug-ins, the availability of an extension varies with deployments and the specific plug-in in use.

Faults

The Networking API v2.0 returns an error response if a failure occurs while processing a request. OpenStack Networking uses only standard HTTP error codes. 4nn errors indicate problems in the particular request being sent from the client.

Error

Description

400

Bad request Malformed request URI or body requested admin state invalid Invalid values entered Bulk operations disallowed Validation failed Method not allowed for request body (such as trying to update attributes that can be specified at create-time only)

404

Not Found Non existent URI Resource not found

409

Conflict Port configured on network IP allocated on subnet Conflicting IP allocation pools for subnet

412

Precondition failed The revision number is mismatched

500

Internal server error Internal OpenStack Networking error

503

Service unavailable Failure in Mac address generation

Users submitting requests to the Networking API v2.0 might also receive the following errors:

  • 401 Unauthorized - If invalid credentials are provided.

  • 403 Forbidden - If the user cannot access a specific resource or perform the requested operation.

Revisions

The Resource revision numbers extension (standard-attr-revisions) adds the revision_number attribute to all API resources that support standard attributes. This includes networks, ports, subnets, subnet pools, floating IPs, routers, logs, security groups/rules, network segments, QoS policies and trunks. As you’d expect, the revision_number indicates the number of updates a particular resource has undergone and is read-only.

In addition, the If-Match constraints based on revision_number extension (revision-if-match) allows API consumers to leverage the If-Match HTTP header to conditionally update/delete a resource when the HTTP If-Match header matches the revision_number of the said resource.

If the HTTP If-Match header doesn’t match the revision_number of the resource, users will receive the following errors:

  • 412 Precondition failed - Update/Delete the target resource has been denied due to the mismatch of revision number.

API versions

Lists information for all Networking API versions.

GET
/

List API versions

Lists information about all Networking API versions.

Normal response codes: 200

Request

Response Parameters

Name

In

Type

Description

versions

body

array

List of versions.

status

body

string

Status of the API, which can be CURRENT, STABLE or DEPRECATED.

id

body

string

Version of the API.

links

body

array

List of version links. Each link is a dict with ‘href’ and ‘rel’.

href

body

string

Link to the API.

rel

body

string

Relationship of link with the version.

Response Example

{
    "versions": [
        {
            "status": "CURRENT",
            "id": "v2.0",
            "links": [
                {
                    "href": "http://23.253.228.211:9696/v2.0",
                    "rel": "self"
                }
            ]
        }
    ]
}
GET
/v2.0/

Show API v2 details

Shows details for Networking API v2.0.

Normal response codes: 200

Error response codes: 401

Request

Response Parameters

Name

In

Type

Description

resources

body

array

List of resource objects.

name

body

string

Name of the resource.

collection

body

string

Collection name of the resource.

links

body

array

List of links related to the resource. Each link is a dict with ‘href’ and ‘rel’.

href

body

string

Link to the resource.

rel

body

string

Relationship between link and the resource.

Response Example

{
    "resources": [
        {
            "links": [
                {
                    "href": "http://23.253.228.211:9696/v2.0/subnets",
                    "rel": "self"
                }
            ],
            "name": "subnet",
            "collection": "subnets"
        },
        {
            "links": [
                {
                    "href": "http://23.253.228.211:9696/v2.0/networks",
                    "rel": "self"
                }
            ],
            "name": "network",
            "collection": "networks"
        },
        {
            "links": [
                {
                    "href": "http://23.253.228.211:9696/v2.0/ports",
                    "rel": "self"
                }
            ],
            "name": "port",
            "collection": "ports"
        }
    ]
}

Extensions

Extensions introduce features and vendor-specific functionality to the API.

GET
/v2.0/extensions

List extensions

Lists available extensions.

Lists available Networking API v2.0 extensions.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Response Parameters

Name

In

Type

Description

extensions

body

array

A list of extension objects.

name

body

string

Human-readable name of the resource.

links

body

array

List of links related to the extension.

alias

body

string

The alias for the extension. For example “quotas” or “security-group”.

updated

body

string

The date and timestamp when the extension was last updated.

description

body

string

The human-readable description for the resource.

Response Example

{
    "extensions": [
        {
            "updated": "2013-01-20T00:00:00-00:00",
            "name": "Neutron Service Type Management",
            "links": [],
            "alias": "service-type",
            "description": "API for retrieving service providers for Neutron advanced services"
        },
        {
            "updated": "2012-10-05T10:00:00-00:00",
            "name": "security-group",
            "links": [],
            "alias": "security-group",
            "description": "The security groups extension."
        },
        {
            "updated": "2013-02-07T10:00:00-00:00",
            "name": "L3 Agent Scheduler",
            "links": [],
            "alias": "l3_agent_scheduler",
            "description": "Schedule routers among l3 agents"
        },
        {
            "updated": "2013-03-28T10:00:00-00:00",
            "name": "Neutron L3 Configurable external gateway mode",
            "links": [],
            "alias": "ext-gw-mode",
            "description": "Extension of the router abstraction for specifying whether SNAT should occur on the external gateway"
        },
        {
            "updated": "2014-02-03T10:00:00-00:00",
            "name": "Port Binding",
            "links": [],
            "alias": "binding",
            "description": "Expose port bindings of a virtual port to external application"
        },
        {
            "updated": "2012-09-07T10:00:00-00:00",
            "name": "Provider Network",
            "links": [],
            "alias": "provider",
            "description": "Expose mapping of virtual networks to physical networks"
        },
        {
            "updated": "2013-02-03T10:00:00-00:00",
            "name": "agent",
            "links": [],
            "alias": "agent",
            "description": "The agent management extension."
        },
        {
            "updated": "2012-07-29T10:00:00-00:00",
            "name": "Quota management support",
            "links": [],
            "alias": "quotas",
            "description": "Expose functions for quotas management per tenant"
        },
        {
            "updated": "2013-02-07T10:00:00-00:00",
            "name": "DHCP Agent Scheduler",
            "links": [],
            "alias": "dhcp_agent_scheduler",
            "description": "Schedule networks among dhcp agents"
        },
        {
            "updated": "2013-06-27T10:00:00-00:00",
            "name": "Multi Provider Network",
            "links": [],
            "alias": "multi-provider",
            "description": "Expose mapping of virtual networks to multiple physical networks"
        },
        {
            "updated": "2013-01-14T10:00:00-00:00",
            "name": "Neutron external network",
            "links": [],
            "alias": "external-net",
            "description": "Adds external network attribute to network resource."
        },
        {
            "updated": "2012-07-20T10:00:00-00:00",
            "name": "Neutron L3 Router",
            "links": [],
            "alias": "router",
            "description": "Router abstraction for basic L3 forwarding between L2 Neutron networks and access to external networks via a NAT gateway."
        },
        {
            "updated": "2013-07-23T10:00:00-00:00",
            "name": "Allowed Address Pairs",
            "links": [],
            "alias": "allowed-address-pairs",
            "description": "Provides allowed address pairs"
        },
        {
            "updated": "2013-03-17T12:00:00-00:00",
            "name": "Neutron Extra DHCP opts",
            "links": [],
            "alias": "extra_dhcp_opt",
            "description": "Extra options configuration for DHCP. For example PXE boot options to DHCP clients can be specified (e.g. tftp-server, server-ip-address, bootfile-name)"
        },
        {
            "updated": "2013-02-01T10:00:00-00:00",
            "name": "Neutron Extra Route",
            "links": [],
            "alias": "extraroute",
            "description": "Extra routes configuration for L3 router"
        },
        {
            "updated": "2016-01-24T10:00:00-00:00",
            "name": "Neutron Port Data Plane Status",
            "links": [],
            "alias": "data-plane-status",
            "description": "Status of the underlying data plane."
        }
    ]
}
GET
/v2.0/extensions/{alias}

Show extension details

Shows details for an extension, by alias. The response shows the extension name and its alias. To show details for an extension, you specify the alias.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

alias

path

string

The alias of an extension.

Response Parameters

Name

In

Type

Description

extension

body

object

An extension object.

name

body

string

Human-readable name of the resource.

links

body

array

List of links related to the extension.

alias

body

string

The alias for the extension. For example “quotas” or “security-group”.

updated

body

string

The date and timestamp when the extension was last updated.

description

body

string

The human-readable description for the resource.

Response Example

{
    "extension": {
        "updated": "2013-02-03T10:00:00-00:00",
        "name": "agent",
        "links": [],
        "alias": "agent",
        "description": "The agent management extension."
    }
}

Layer 2 Networking

Networks

Lists, shows details for, creates, updates, and deletes networks.

Address Scopes Extension

The address-scope extension adds the ipv4_address_scope and ipv6_address_scope attributes to networks. ipv4_address_scope is the ID of the IPv4 address scope that the network is associated with. ipv6_address_scope is the ID of the IPv6 address scope that the network is associated with.

Auto Allocated Topology

The auto-allocated-topology extension adds the is_default boolean attribute to networks. This value indicates the network should be used when auto allocating topologies.

DNS integration

The dns-integration extension adds the dns_domain attribute to networks. The dns_domain of a network in conjunction with the dns_name attribute of its ports will be published in an external DNS service when Neutron is configured to integrate with such a service.

External network

The external-net extension adds the router:external attribute to networks. This boolean attribute indicates the network has an external routing facility that’s not managed by the networking service.

FloatingIP autodelete internal

The floatingip-autodelete-internal shim extension signals that the update of a network’s router:external attribute from true to false autodeletes the unused Floating IPs of that network.

HA extension

The network-ha extension allows to pass a boolean parameter during the network creation. If true is passed, a ha_router_networks database register will be created along with the network register. This field is not visible and, initially, not meant to be supported in the CLI.

L2 adjacency extension

The l2_adjacency extension provides display of L2 Adjacency for networks by adding the read-only l2_adjacency attribute. This is a boolean value where true means that you can expect L2 connectivity throughout the Network and false means that there is no guarantee of L2 connectivity. This value is read-only and is derived from the current state of segments within the network.

MTU extensions

The net-mtu extension allows plug-ins to expose the MTU that is guaranteed to pass through the data path of the segments in the network. This extension introduces a read-only mtu attribute.

A newer net-mtu-writable extension enhances net-mtu in that now the mtu attribute is available for write (both when creating as well as updating networks).

Warning

Due to limitations in libvirt and QEMU, updating the mtu value for an existing network with instances plugged into it requires either a hard reboot of those instances, or a detach and re-attach of their ports from that network.

Multiple provider extension

The multi-provider extension allows administrative users to define multiple physical bindings for a logical network.

To define multiple physical bindings for a network, include a segments list in the request body of network creation request. Each element in the segments list has the same structure as the provider network attributes. These attributes are provider:network_type, provider:physical_network, and provider:segmentation_id. The same validation rules are applied to each element in the segments list.

Note that you cannot use the provider extension and the multiple provider extension for a single logical network.

Network availability zone extension

The network_availability_zone extension provides support of availability zone for networks, exposing availability_zone_hints and availability_zones attributes.

Network cascade delete extension

The network-cascade-delete shim extension adds to networks the optional boolean attribute, cascade, that when defined as true, removes all child objects of a network upon its deletion.

Port security

The port-security extension adds the port_security_enabled boolean attribute to networks. At the network level, port_security_enabled defines the default value for new ports attached to the network; they will inherit the value of their network’s port_security_enabled unless explicitly set on the port itself. While the default value for port_security_enabled is true, this can be changed by updating the respective network. Note that changing a value of port_security_enabled on a network, does not cascade the value to ports attached to the network.

Provider extended attributes

The provider extension allows administrative users to define a physical binding of a logical network. This extension provides three additional attributes: provider:network_type, provider:physical_network and provider:segmentation_id. The validation rules for these attributes vary across provider:network_type. For example, vlan and flat network types require provider:physical_network attribute, but vxlan network type does not.

Most Networking plug-ins (e.g. ML2 Plugin) and drivers do not support updating any provider related attributes. Check your plug-in whether it supports updating.

QoS extension

The QoS extension (qos) makes it possible to define QoS policies and associate these to the networks by introducing the qos_policy_id attribute. The policies should be created before they are associated to the networks.

Resource timestamps

The standard-attr-timestamp extension adds the created_at and updated_at attributes to all resources that have standard attributes.

Tag extension

The standard-attr-tag adds Tag support for resources with standard attributes by adding the tags attribute allowing consumers to associate tags with resources.

VLAN transparency extension

The vlan-transparent extension enables plug-ins that support VLAN transparency to deliver VLAN transparent trunk networks. This extension introduces a vlan_transparent attribute to control the VLAN transparency of the network. If the service does not support VLAN transparency and a user requests a VLAN transparent network, the plug-in refuses to create one and returns an appropriate error to the user.

GET
/v2.0/networks/{network_id}

Show network details

Shows details for a network.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

network_id

path

string

The ID of the network.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

network

body

object

A network object.

admin_state_up

body

boolean

The administrative state of the network, which is up (true) or down (false).

availability_zone_hints

body

array

The availability zone candidate for the network.

availability_zones

body

array

The availability zone for the network.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

dns_domain

body

string

A valid DNS domain.

id

body

string

The ID of the network.

ipv4_address_scope

body

string

The ID of the IPv4 address scope that the network is associated with.

ipv6_address_scope

body

string

The ID of the IPv6 address scope that the network is associated with.

l2_adjacency

body

boolean

Indicates whether L2 connectivity is available throughout the network.

mtu

body

integer

The maximum transmission unit (MTU) value to address fragmentation. Minimum value is 68 for IPv4, and 1280 for IPv6.

name

body

string

Human-readable name of the network.

port_security_enabled

body

boolean

The port security status of the network. Valid values are enabled (true) and disabled (false). This value is used as the default value of port_security_enabled field of a newly created port.

project_id

body

string

The ID of the project.

provider:network_type

body

string

The type of physical network that this network is mapped to. For example, flat, vlan, vxlan, or gre. Valid values depend on a networking back-end.

provider:physical_network

body

string

The physical network where this network/segment is implemented.

provider:segmentation_id

body

integer

The ID of the isolated segment on the physical network. The network_type attribute defines the segmentation model. For example, if the network_type value is vlan, this ID is a vlan identifier. If the network_type value is gre, this ID is a gre key. Note that only the segmentation-id of VLAN type networks can be changed!

qos_policy_id

body

string

The ID of the QoS policy associated with the network.

revision_number

body

integer

The revision number of the resource.

router:external

body

boolean

Defines whether the network may be used for creation of floating IPs. Only networks with this flag may be an external gateway for routers. The network must have an external routing facility that is not managed by the networking service. If the network is updated from external to internal the unused floating IPs of this network are automatically deleted when extension floatingip-autodelete-internal is present.

segments

body

array

A list of provider segment objects.

shared

body

boolean

Indicates whether this network is shared across all tenants. By default, only administrative users can change this value.

status

body

string

The network status. Values are ACTIVE, DOWN, BUILD or ERROR.

subnets

body

array

The associated subnets.

tenant_id

body

string

The ID of the project.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

vlan_transparent

body

boolean

Indicates the VLAN transparency mode of the network, which is VLAN transparent (true) or not VLAN transparent (false).

description

body

string

A human-readable description for the resource.

is_default

body

boolean

The network is default pool or not.

tags

body

array

The list of tags on the resource.

Response Example

{
    "network": {
        "admin_state_up": true,
        "availability_zone_hints": [],
        "availability_zones": [
            "nova"
        ],
        "created_at": "2016-03-08T20:19:41",
        "dns_domain": "my-domain.org.",
        "id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
        "ipv4_address_scope": null,
        "ipv6_address_scope": null,
        "l2_adjacency": false,
        "mtu": 1500,
        "name": "private-network",
        "port_security_enabled": true,
        "project_id": "4fd44f30292945e481c7b8a0c8908869",
        "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e",
        "revision_number": 1,
        "router:external": false,
        "shared": true,
        "status": "ACTIVE",
        "subnets": [
            "54d6f61d-db07-451c-9ab3-b9609b6b6f0b"
        ],
        "tags": ["tag1,tag2"],
        "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
        "updated_at": "2016-03-08T20:19:41",
        "vlan_transparent": false,
        "description": "",
        "is_default": true
    }
}

Response Example (admin user; single segment mapping)

{
    "network": {
        "admin_state_up": true,
        "availability_zone_hints": [],
        "availability_zones": [
            "nova"
        ],
        "created_at": "2016-03-08T20:19:41",
        "dns_domain": "my-domain.org.",
        "id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
        "ipv4_address_scope": null,
        "ipv6_address_scope": null,
        "l2_adjacency": false,
        "mtu": 1500,
        "name": "private-network",
        "port_security_enabled": true,
        "project_id": "4fd44f30292945e481c7b8a0c8908869",
        "provider:network_type": "local",
        "provider:physical_network": null,
        "provider:segmentation_id": null,
        "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e",
        "revision_number": 1,
        "router:external": false,
        "shared": true,
        "status": "ACTIVE",
        "subnets": [
            "54d6f61d-db07-451c-9ab3-b9609b6b6f0b"
        ],
        "tags": ["tag1,tag2"],
        "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
        "updated_at": "2016-03-08T20:19:41",
        "vlan_transparent": false,
        "description": "",
        "is_default": true
    }
}

Response Example (admin user; multiple segment mappings)

{
    "network": {
        "admin_state_up": true,
        "availability_zone_hints": [],
        "availability_zones": [
            "nova"
        ],
        "created_at": "2016-03-08T20:19:41",
        "dns_domain": "my-domain.org.",
        "id": "4e8e5957-649f-477b-9e5b-f1f75b21c03c",
        "ipv4_address_scope": null,
        "ipv6_address_scope": null,
        "l2_adjacency": false,
        "mtu": 1500,
        "name": "net1",
        "port_security_enabled": true,
        "project_id": "9bacb3c5d39d41a79512987f338cf177",
        "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e",
        "revision_number": 1,
        "router:external": false,
        "segments": [
            {
                "provider:network_type": "vlan",
                "provider:physical_network": "public",
                "provider:segmentation_id": 2
            },
            {
                "provider:network_type": "flat",
                "provider:physical_network": "default",
                "provider:segmentation_id": 0
            }
        ],
        "shared": false,
        "status": "ACTIVE",
        "subnets": [
            "54d6f61d-db07-451c-9ab3-b9609b6b6f0b"
        ],
        "tags": ["tag1,tag2"],
        "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
        "updated_at": "2016-03-08T20:19:41",
        "vlan_transparent": false,
        "description": "",
        "is_default": false
    }
}
PUT
/v2.0/networks/{network_id}

Update network

Updates a network.

Normal response codes: 200

Error response codes: 400, 401, 403, 404, 412

Request

Name

In

Type

Description

network_id

path

string

The ID of the network.

network

body

object

A network object.

admin_state_up (Optional)

body

boolean

The administrative state of the network, which is up (true) or down (false).

dns_domain (Optional)

body

string

A valid DNS domain.

mtu (Optional)

body

integer

The maximum transmission unit (MTU) value to address fragmentation. Minimum value is 68 for IPv4, and 1280 for IPv6.

name (Optional)

body

string

Human-readable name of the network.

port_security_enabled (Optional)

body

boolean

The port security status of the network. Valid values are enabled (true) and disabled (false). This value is used as the default value of port_security_enabled field of a newly created port.

provider:network_type

body

string

The type of physical network that this network is mapped to. For example, flat, vlan, vxlan, or gre. Valid values depend on a networking back-end.

provider:physical_network

body

string

The physical network where this network/segment is implemented.

provider:segmentation_id

body

integer

The ID of the isolated segment on the physical network. The network_type attribute defines the segmentation model. For example, if the network_type value is vlan, this ID is a vlan identifier. If the network_type value is gre, this ID is a gre key. Note that only the segmentation-id of VLAN type networks can be changed!

qos_policy_id (Optional)

body

string

The ID of the QoS policy associated with the network.

router:external (Optional)

body

boolean

Indicates whether the network has an external routing facility that’s not managed by the networking service.

segments

body

array

A list of provider segment objects.

shared (Optional)

body

boolean

Indicates whether this resource is shared across all projects. By default, only administrative users can change this value.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

is_default (Optional)

body

boolean

The network is default or not.

Request Example

{
    "network": {
        "dns_domain": "my-domain.org.",
        "name": "sample_network_5_updated",
        "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e",
        "mtu": 1300
    }
}

Request Example (admin user; single segment mapping)

{
    "network": {
        "provider:network_type": "vlan",
        "provider:physical_network": "public",
        "provider:segmentation_id": 2
    }
}

Request Example (admin user; multiple segment mappings)

{
    "network": {
        "segments": [
            {
                "provider:segmentation_id": 2,
                "provider:physical_network": "public",
                "provider:network_type": "vlan"
            },
            {
                "provider:physical_network": "default",
                "provider:network_type": "flat"
            }
        ]
    }
}

Response Parameters

Name

In

Type

Description

network

body

object

A network object.

admin_state_up

body

boolean

The administrative state of the network, which is up (true) or down (false).

availability_zone_hints

body

array

The availability zone candidate for the network.

availability_zones

body

array

The availability zone for the network.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

dns_domain

body

string

A valid DNS domain.

id

body

string

The ID of the network.

ipv4_address_scope

body

string

The ID of the IPv4 address scope that the network is associated with.

ipv6_address_scope

body

string

The ID of the IPv6 address scope that the network is associated with.

l2_adjacency

body

boolean

Indicates whether L2 connectivity is available throughout the network.

mtu

body

integer

The maximum transmission unit (MTU) value to address fragmentation. Minimum value is 68 for IPv4, and 1280 for IPv6.

name

body

string

Human-readable name of the network.

port_security_enabled

body

boolean

The port security status of the network. Valid values are enabled (true) and disabled (false). This value is used as the default value of port_security_enabled field of a newly created port.

project_id

body

string

The ID of the project.

provider:network_type

body

string

The type of physical network that this network is mapped to. For example, flat, vlan, vxlan, or gre. Valid values depend on a networking back-end.

provider:physical_network

body

string

The physical network where this network/segment is implemented.

provider:segmentation_id

body

integer

The ID of the isolated segment on the physical network. The network_type attribute defines the segmentation model. For example, if the network_type value is vlan, this ID is a vlan identifier. If the network_type value is gre, this ID is a gre key. Note that only the segmentation-id of VLAN type networks can be changed!

qos_policy_id

body

string

The ID of the QoS policy associated with the network.

revision_number

body

integer

The revision number of the resource.

router:external

body

boolean

Defines whether the network may be used for creation of floating IPs. Only networks with this flag may be an external gateway for routers. The network must have an external routing facility that is not managed by the networking service. If the network is updated from external to internal the unused floating IPs of this network are automatically deleted when extension floatingip-autodelete-internal is present.

segments

body

array

A list of provider segment objects.

shared

body

boolean

Indicates whether this network is shared across all tenants. By default, only administrative users can change this value.

status

body

string

The network status. Values are ACTIVE, DOWN, BUILD or ERROR.

subnets

body

array

The associated subnets.

tenant_id

body

string

The ID of the project.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

description

body

string

A human-readable description for the resource.

is_default

body

boolean

The network is default pool or not.

tags

body

array

The list of tags on the resource.

Response Example

This is an example when a regular user without administrative roles sends a PUT request. Response examples for administrative users are similar to responses of Show network details and Create network. See them for details.

{
    "network": {
        "admin_state_up": true,
        "availability_zone_hints": [],
        "availability_zones": [
            "nova"
        ],
        "created_at": "2016-03-08T20:19:41",
        "dns_domain": "my-domain.org.",
        "id": "1f370095-98f6-4079-be64-6d3d4a6adcc6",
        "ipv4_address_scope": null,
        "ipv6_address_scope": null,
        "l2_adjacency": false,
        "mtu": 1300,
        "name": "sample_network_5_updated",
        "port_security_enabled": true,
        "project_id": "4fd44f30292945e481c7b8a0c8908869",
        "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e",
        "revision_number": 2,
        "router:external": false,
        "shared": false,
        "status": "ACTIVE",
        "subnets": [
            "54d6f61d-db07-451c-9ab3-b9609b6b6f0b"
        ],
        "tags": ["tag1,tag2"],
        "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
        "updated_at": "2016-03-08T20:19:41",
        "vlan_transparent": false,
        "description": "",
        "is_default": false
    }
}
DELETE
/v2.0/networks/{network_id}

Delete network

Deletes a network and its associated resources.

Normal response codes: 204

Error response codes: 401, 404, 409, 412

Request

Name

In

Type

Description

network_id

path

string

The ID of the network.

Response

There is no body content for the response of a successful DELETE request.

GET
/v2.0/networks

List networks

Lists networks to which the project has access.

Default policy settings return only networks that the project who submits the request owns, unless an administrative user submits the request. In addition, networks shared with the project who submits the request are also returned.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

You can also use the tags, tags-any, not-tags, not-tags-any query parameter to filter the response with tags. For information, see REST API Impact.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

admin_state_up (Optional)

query

boolean

Filter the list result by the administrative state of the resource, which is up (true) or down (false).

id (Optional)

query

string

Filter the list result by the ID of the resource.

mtu (Optional)

query

integer

Filter the network list result by the maximum transmission unit (MTU) value to address fragmentation. Minimum value is 68 for IPv4, and 1280 for IPv6.

name (Optional)

query

string

Filter the list result by the human-readable name of the resource.

project_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

provider:network_type (Optional)

query

string

Filter the list result by the type of physical network that this network/segment is mapped to. For example, flat, vlan, vxlan, or gre. Valid values depend on a networking back-end.

provider:physical_network (Optional)

query

string

Filter the list result by the physical network where this network/segment is implemented.

provider:segmentation_id (Optional)

query

integer

Filter the list result by the ID of the isolated segment on the physical network.

revision_number (Optional)

query

integer

Filter the list result by the revision number of the resource.

router:external (Optional)

query

boolean

Filter the network list result based on whether the network has an external routing facility that’s not managed by the networking service.

shared (Optional)

query

boolean

Filter the network list result based on if the network is shared across all tenants.

status (Optional)

query

string

Filter the network list result by network status. Values are ACTIVE, DOWN, BUILD or ERROR.

tenant_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

vlan_transparent (Optional)

query

boolean

Filter the network list by the VLAN transparency mode of the network, which is VLAN transparent (true) or not VLAN transparent (false).

description (Optional)

query

string

Filter the list result by the human-readable description of the resource.

is_default (Optional)

query

boolean

Filter the network list result based on if the network is default pool or not.

tags (Optional)

query

string

A list of tags to filter the list result by. Resources that match all tags in this list will be returned. Tags in query must be separated by comma.

tags-any (Optional)

query

string

A list of tags to filter the list result by. Resources that match any tag in this list will be returned. Tags in query must be separated by comma.

not-tags (Optional)

query

string

A list of tags to filter the list result by. Resources that match all tags in this list will be excluded. Tags in query must be separated by comma.

not-tags-any (Optional)

query

string

A list of tags to filter the list result by. Resources that match any tag in this list will be excluded. Tags in query must be separated by comma.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a network attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • admin_state_up

  • availability_zone_hints

  • id

  • mtu

  • name

  • status

  • tenant_id

  • project_id

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

networks

body

array

A list of network objects.

admin_state_up

body

boolean

The administrative state of the network, which is up (true) or down (false).

availability_zone_hints

body

array

The availability zone candidate for the network.

availability_zones

body

array

The availability zone for the network.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

dns_domain

body

string

A valid DNS domain.

id

body

string

The ID of the network.

ipv4_address_scope

body

string

The ID of the IPv4 address scope that the network is associated with.

ipv6_address_scope

body

string

The ID of the IPv6 address scope that the network is associated with.

l2_adjacency

body

boolean

Indicates whether L2 connectivity is available throughout the network.

mtu

body

integer

The maximum transmission unit (MTU) value to address fragmentation. Minimum value is 68 for IPv4, and 1280 for IPv6.

name

body

string

Human-readable name of the network.

port_security_enabled

body

boolean

The port security status of the network. Valid values are enabled (true) and disabled (false). This value is used as the default value of port_security_enabled field of a newly created port.

project_id

body

string

The ID of the project.

provider:network_type

body

string

The type of physical network that this network is mapped to. For example, flat, vlan, vxlan, or gre. Valid values depend on a networking back-end.

provider:physical_network

body

string

The physical network where this network/segment is implemented.

provider:segmentation_id

body

integer

The ID of the isolated segment on the physical network. The network_type attribute defines the segmentation model. For example, if the network_type value is vlan, this ID is a vlan identifier. If the network_type value is gre, this ID is a gre key. Note that only the segmentation-id of VLAN type networks can be changed!

qos_policy_id

body

string

The ID of the QoS policy associated with the network.

revision_number

body

integer

The revision number of the resource.

router:external

body

boolean

Defines whether the network may be used for creation of floating IPs. Only networks with this flag may be an external gateway for routers. The network must have an external routing facility that is not managed by the networking service. If the network is updated from external to internal the unused floating IPs of this network are automatically deleted when extension floatingip-autodelete-internal is present.

segments

body

array

A list of provider segment objects.

shared

body

boolean

Indicates whether this network is shared across all tenants. By default, only administrative users can change this value.

status

body

string

The network status. Values are ACTIVE, DOWN, BUILD or ERROR.

subnets

body

array

The associated subnets.

tenant_id

body

string

The ID of the project.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

vlan_transparent

body

boolean

Indicates the VLAN transparency mode of the network, which is VLAN transparent (true) or not VLAN transparent (false).

description

body

string

A human-readable description for the resource.

is_default

body

boolean

The network is default pool or not.

tags

body

array

The list of tags on the resource.

Response Example

{
    "networks": [
        {
            "admin_state_up": true,
            "availability_zone_hints": [],
            "availability_zones": [
                "nova"
            ],
            "created_at": "2016-03-08T20:19:41",
            "dns_domain": "my-domain.org.",
            "id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
            "ipv4_address_scope": null,
            "ipv6_address_scope": null,
            "l2_adjacency": false,
            "mtu": 1500,
            "name": "net1",
            "port_security_enabled": true,
            "project_id": "4fd44f30292945e481c7b8a0c8908869",
            "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e",
            "revision_number": 1,
            "router:external": false,
            "shared": false,
            "status": "ACTIVE",
            "subnets": [
                "54d6f61d-db07-451c-9ab3-b9609b6b6f0b"
            ],
            "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
            "updated_at": "2016-03-08T20:19:41",
            "vlan_transparent": true,
            "description": "",
            "is_default": false
        },
        {
            "admin_state_up": true,
            "availability_zone_hints": [],
            "availability_zones": [
                "nova"
            ],
            "created_at": "2016-03-08T20:19:41",
            "dns_domain": "my-domain.org.",
            "id": "db193ab3-96e3-4cb3-8fc5-05f4296d0324",
            "ipv4_address_scope": null,
            "ipv6_address_scope": null,
            "l2_adjacency": false,
            "mtu": 1500,
            "name": "net2",
            "port_security_enabled": true,
            "project_id": "26a7980765d0414dbc1fc1f88cdb7e6e",
            "qos_policy_id": "bfdb6c39f71e4d44b1dfbda245c50819",
            "revision_number": 3,
            "router:external": false,
            "shared": false,
            "status": "ACTIVE",
            "subnets": [
                "08eae331-0402-425a-923c-34f7cfe39c1b"
            ],
            "tenant_id": "26a7980765d0414dbc1fc1f88cdb7e6e",
            "updated_at": "2016-03-08T20:19:41",
            "vlan_transparent": false,
            "description": "",
            "is_default": false
        }
    ]
}

Response Example (admin user)

When Administrative users request to list networks, physical segment information bound to the networks are also returned in a response. In this example, a network net1 is mapped to a single network segment and a network net2 is mapped to multiple network segments.

{
    "networks": [
        {
            "admin_state_up": true,
            "availability_zone_hints": [],
            "availability_zones": [
                "nova"
            ],
            "created_at": "2016-03-08T20:19:41",
            "dns_domain": "my-domain.org.",
            "id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
            "ipv4_address_scope": null,
            "ipv6_address_scope": null,
            "l2_adjacency": false,
            "mtu": 1500,
            "name": "net1",
            "port_security_enabled": true,
            "project_id": "4fd44f30292945e481c7b8a0c8908869",
            "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e",
            "provider:network_type": "vlan",
            "provider:physical_network": "public",
            "provider:segmentation_id": 3,
            "revision_number": 1,
            "router:external": false,
            "shared": false,
            "status": "ACTIVE",
            "subnets": [
                "54d6f61d-db07-451c-9ab3-b9609b6b6f0b"
            ],
            "tags": ["tag1,tag2"],
            "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
            "updated_at": "2016-03-08T20:19:41",
            "vlan_transparent": true,
            "description": "",
            "is_default": false
        },
        {
            "admin_state_up": true,
            "availability_zone_hints": [],
            "availability_zones": [
                "nova"
            ],
            "created_at": "2016-03-08T20:19:41",
            "dns_domain": "my-domain.org.",
            "id": "db193ab3-96e3-4cb3-8fc5-05f4296d0324",
            "ipv4_address_scope": null,
            "ipv6_address_scope": null,
            "l2_adjacency": false,
            "mtu": 1450,
            "name": "net2",
            "port_security_enabled": true,
            "project_id": "26a7980765d0414dbc1fc1f88cdb7e6e",
            "qos_policy_id": null,
            "provider:network_type": "local",
            "provider:physical_network": null,
            "provider:segmentation_id": null,
            "qos_policy_id": "bfdb6c39f71e4d44b1dfbda245c50819",
            "revision_number": 2,
            "router:external": false,
            "segments": [
                {
                    "provider:network_type": "vlan",
                    "provider:physical_network": "public",
                    "provider:segmentation_id": 2
                },
                {
                    "provider:network_type": "vxlan",
                    "provider:physical_network": "default",
                    "provider:segmentation_id": 1000
                }
            ],
            "shared": false,
            "status": "ACTIVE",
            "subnets": [
                "08eae331-0402-425a-923c-34f7cfe39c1b"
            ],
            "tags": ["tag1,tag2"],
            "tenant_id": "26a7980765d0414dbc1fc1f88cdb7e6e",
            "updated_at": "2016-03-08T20:19:41",
            "vlan_transparent": false,
            "description": "",
            "is_default": false
        }
    ]
}
POST
/v2.0/networks

Create network

Creates a network.

A request body is optional. An administrative user can specify another project ID, which is the project that owns the network, in the request body.

Normal response codes: 201

Error response codes: 400, 401

Request

Name

In

Type

Description

network

body

object

A network object.

admin_state_up (Optional)

body

boolean

The administrative state of the network, which is up (true) or down (false).

dns_domain (Optional)

body

string

A valid DNS domain.

mtu (Optional)

body

integer

The maximum transmission unit (MTU) value to address fragmentation. Minimum value is 68 for IPv4, and 1280 for IPv6.

name (Optional)

body

string

Human-readable name of the network.

port_security_enabled (Optional)

body

boolean

The port security status of the network. Valid values are enabled (true) and disabled (false). This value is used as the default value of port_security_enabled field of a newly created port.

project_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

provider:network_type (Optional)

body

string

The type of physical network that this network should be mapped to. For example, flat, vlan, vxlan, or gre. Valid values depend on a networking back-end.

provider:physical_network (Optional)

body

string

The physical network where this network should be implemented. The Networking API v2.0 does not provide a way to list available physical networks. For example, the Open vSwitch plug-in configuration file defines a symbolic name that maps to specific bridges on each compute host.

provider:segmentation_id (Optional)

body

integer

The ID of the isolated segment on the physical network. The network_type attribute defines the segmentation model. For example, if the network_type value is vlan, this ID is a vlan identifier. If the network_type value is gre, this ID is a gre key.

qos_policy_id (Optional)

body

string

The ID of the QoS policy associated with the network.

router:external (Optional)

body

boolean

Indicates whether the network has an external routing facility that’s not managed by the networking service.

segments (Optional)

body

array

A list of provider segment objects.

shared (Optional)

body

boolean

Indicates whether this resource is shared across all projects. By default, only administrative users can change this value.

tenant_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

vlan_transparent (Optional)

body

boolean

Indicates the VLAN transparency mode of the network, which is VLAN transparent (true) or not VLAN transparent (false).

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

is_default (Optional)

body

boolean

The network is default or not.

availability_zone_hints (Optional)

body

array

The availability zone candidate for the network.

Request Example

{
    "network": {
        "name": "sample_network",
        "admin_state_up": true,
        "dns_domain": "my-domain.org.",
        "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e",
        "mtu": 1400
    }
}

Request Example (admin user; single segment mapping)

{
    "network": {
        "admin_state_up": true,
        "name": "net1",
        "provider:network_type": "vlan",
        "provider:physical_network": "public",
        "provider:segmentation_id": 2,
        "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e"
    }
}

Request Example (admin user; multiple segment mappings)

{
    "network": {
        "segments": [
            {
                "provider:segmentation_id": 2,
                "provider:physical_network": "public",
                "provider:network_type": "vlan"
            },
            {
                "provider:physical_network": "default",
                "provider:network_type": "flat"
            }
        ],
        "name": "net1",
        "admin_state_up": true,
        "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e"
    }
}

Response Parameters

Name

In

Type

Description

network

body

object

A network object.

admin_state_up

body

boolean

The administrative state of the network, which is up (true) or down (false).

availability_zone_hints

body

array

The availability zone candidate for the network.

availability_zones

body

array

The availability zone for the network.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

dns_domain

body

string

A valid DNS domain.

id

body

string

The ID of the network.

ipv4_address_scope

body

string

The ID of the IPv4 address scope that the network is associated with.

ipv6_address_scope

body

string

The ID of the IPv6 address scope that the network is associated with.

l2_adjacency

body

boolean

Indicates whether L2 connectivity is available throughout the network.

mtu

body

integer

The maximum transmission unit (MTU) value to address fragmentation. Minimum value is 68 for IPv4, and 1280 for IPv6.

name

body

string

Human-readable name of the network.

port_security_enabled

body

boolean

The port security status of the network. Valid values are enabled (true) and disabled (false). This value is used as the default value of port_security_enabled field of a newly created port.

project_id

body

string

The ID of the project.

provider:network_type

body

string

The type of physical network that this network is mapped to. For example, flat, vlan, vxlan, or gre. Valid values depend on a networking back-end.

provider:physical_network

body

string

The physical network where this network/segment is implemented.

provider:segmentation_id

body

integer

The ID of the isolated segment on the physical network. The network_type attribute defines the segmentation model. For example, if the network_type value is vlan, this ID is a vlan identifier. If the network_type value is gre, this ID is a gre key. Note that only the segmentation-id of VLAN type networks can be changed!

qos_policy_id

body

string

The ID of the QoS policy associated with the network.

revision_number

body

integer

The revision number of the resource.

router:external

body

boolean

Defines whether the network may be used for creation of floating IPs. Only networks with this flag may be an external gateway for routers. The network must have an external routing facility that is not managed by the networking service. If the network is updated from external to internal the unused floating IPs of this network are automatically deleted when extension floatingip-autodelete-internal is present.

segments

body

array

A list of provider segment objects.

shared

body

boolean

Indicates whether this network is shared across all tenants. By default, only administrative users can change this value.

status

body

string

The network status. Values are ACTIVE, DOWN, BUILD or ERROR.

subnets

body

array

The associated subnets.

tenant_id

body

string

The ID of the project.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

vlan_transparent

body

boolean

Indicates the VLAN transparency mode of the network, which is VLAN transparent (true) or not VLAN transparent (false).

description

body

string

A human-readable description for the resource.

is_default

body

boolean

The network is default pool or not.

tags

body

array

The list of tags on the resource.

Response Example

{
    "network": {
        "admin_state_up": true,
        "availability_zone_hints": [],
        "availability_zones": [
            "nova"
        ],
        "created_at": "2016-03-08T20:19:41",
        "dns_domain": "my-domain.org.",
        "id": "4e8e5957-649f-477b-9e5b-f1f75b21c03c",
        "ipv4_address_scope": null,
        "ipv6_address_scope": null,
        "l2_adjacency": true,
        "mtu": 1400,
        "name": "net1",
        "port_security_enabled": true,
        "project_id": "9bacb3c5d39d41a79512987f338cf177",
        "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e",
        "revision_number": 1,
        "router:external": false,
        "shared": false,
        "status": "ACTIVE",
        "subnets": [],
        "tags": ["tag1,tag2"],
        "tenant_id": "9bacb3c5d39d41a79512987f338cf177",
        "updated_at": "2016-03-08T20:19:41",
        "vlan_transparent": false,
        "description": "",
        "is_default": false
    }
}

Response Example (admin user; single segment mapping)

{
    "network": {
        "status": "ACTIVE",
        "subnets": [],
        "availability_zone_hints": [],
        "availability_zones": [
            "nova"
        ],
        "created_at": "2016-03-08T20:19:41",
        "dns_domain": "",
        "ipv4_address_scope": null,
        "ipv6_address_scope": null,
        "name": "net1",
        "provider:physical_network": "public",
        "admin_state_up": true,
        "project_id": "9bacb3c5d39d41a79512987f338cf177",
        "tags": ["tag1,tag2"],
        "tenant_id": "9bacb3c5d39d41a79512987f338cf177",
        "updated_at": "2016-03-08T20:19:41",
        "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e",
        "revision_number": 1,
        "router:external": false,
        "provider:network_type": "vlan",
        "l2_adjacency": true,
        "mtu": 1500,
        "shared": false,
        "id": "4e8e5957-649f-477b-9e5b-f1f75b21c03c",
        "provider:segmentation_id": 2,
        "description": "",
        "port_security_enabled": true,
        "is_default": false
    }
}

Response Example (admin user; multiple segment mappings)

{
    "network": {
        "status": "ACTIVE",
        "subnets": [],
        "availability_zone_hints": [],
        "availability_zones": [
            "nova"
        ],
        "created_at": "2016-03-08T20:19:41",
        "name": "net1",
        "admin_state_up": true,
        "dns_domain": "",
        "ipv4_address_scope": null,
        "ipv6_address_scope": null,
        "l2_adjacency": true,
        "mtu": 1500,
        "port_security_enabled": true,
        "project_id": "9bacb3c5d39d41a79512987f338cf177",
        "tags": ["tag1,tag2"],
        "tenant_id": "9bacb3c5d39d41a79512987f338cf177",
        "updated_at": "2016-03-08T20:19:41",
        "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e",
        "revision_number": 1,
        "segments": [
            {
                "provider:segmentation_id": 2,
                "provider:physical_network": "public",
                "provider:network_type": "vlan"
            },
            {
                "provider:segmentation_id": null,
                "provider:physical_network": "default",
                "provider:network_type": "flat"
            }
        ],
        "shared": false,
        "id": "4e8e5957-649f-477b-9e5b-f1f75b21c03c",
        "description": "",
        "is_default": false
    }
}
POST
/v2.0/networks

Bulk create networks

Creates multiple networks in a single request.

In the request body, specify a list of networks.

The bulk create operation is always atomic. Either all or no networks in the request body are created.

Normal response codes: 201

Error response codes: 400, 401

Request

Name

In

Type

Description

networks

body

array

A list of network objects.

admin_state_up (Optional)

body

boolean

The administrative state of the network, which is up (true) or down (false).

dns_domain (Optional)

body

string

A valid DNS domain.

mtu (Optional)

body

integer

The maximum transmission unit (MTU) value to address fragmentation. Minimum value is 68 for IPv4, and 1280 for IPv6.

name (Optional)

body

string

Human-readable name of the network.

port_security_enabled (Optional)

body

boolean

The port security status of the network. Valid values are enabled (true) and disabled (false). This value is used as the default value of port_security_enabled field of a newly created port.

project_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

provider:network_type (Optional)

body

string

The type of physical network that this network should be mapped to. For example, flat, vlan, vxlan, or gre. Valid values depend on a networking back-end.

provider:physical_network (Optional)

body

string

The physical network where this network should be implemented. The Networking API v2.0 does not provide a way to list available physical networks. For example, the Open vSwitch plug-in configuration file defines a symbolic name that maps to specific bridges on each compute host.

provider:segmentation_id (Optional)

body

integer

The ID of the isolated segment on the physical network. The network_type attribute defines the segmentation model. For example, if the network_type value is vlan, this ID is a vlan identifier. If the network_type value is gre, this ID is a gre key.

qos_policy_id (Optional)

body

string

The ID of the QoS policy associated with the network.

router:external (Optional)

body

boolean

Indicates whether the network has an external routing facility that’s not managed by the networking service.

segments (Optional)

body

array

A list of provider segment objects.

shared (Optional)

body

boolean

Indicates whether this resource is shared across all projects. By default, only administrative users can change this value.

tenant_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

vlan_transparent (Optional)

body

boolean

Indicates the VLAN transparency mode of the network, which is VLAN transparent (true) or not VLAN transparent (false).

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

availability_zone_hints (Optional)

body

array

The availability zone candidate for the network.

Request Example

{
    "networks": [
        {
            "admin_state_up": true,
            "name": "sample_network3",
            "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e"
        },
        {
            "admin_state_up": true,
            "name": "sample_network4",
            "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e"
        }
    ]
}

Response Parameters

Name

In

Type

Description

networks

body

array

A list of network objects.

admin_state_up

body

boolean

The administrative state of the network, which is up (true) or down (false).

availability_zone_hints

body

array

The availability zone candidate for the network.

availability_zones

body

array

The availability zone for the network.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

dns_domain

body

string

A valid DNS domain.

id

body

string

The ID of the network.

ipv4_address_scope

body

string

The ID of the IPv4 address scope that the network is associated with.

ipv6_address_scope

body

string

The ID of the IPv6 address scope that the network is associated with.

l2_adjacency

body

boolean

Indicates whether L2 connectivity is available throughout the network.

mtu

body

integer

The maximum transmission unit (MTU) value to address fragmentation. Minimum value is 68 for IPv4, and 1280 for IPv6.

name

body

string

Human-readable name of the network.

port_security_enabled

body

boolean

The port security status of the network. Valid values are enabled (true) and disabled (false). This value is used as the default value of port_security_enabled field of a newly created port.

project_id

body

string

The ID of the project.

provider:network_type

body

string

The type of physical network that this network is mapped to. For example, flat, vlan, vxlan, or gre. Valid values depend on a networking back-end.

provider:physical_network

body

string

The physical network where this network/segment is implemented.

provider:segmentation_id

body

integer

The ID of the isolated segment on the physical network. The network_type attribute defines the segmentation model. For example, if the network_type value is vlan, this ID is a vlan identifier. If the network_type value is gre, this ID is a gre key. Note that only the segmentation-id of VLAN type networks can be changed!

qos_policy_id

body

string

The ID of the QoS policy associated with the network.

revision_number

body

integer

The revision number of the resource.

router:external

body

boolean

Defines whether the network may be used for creation of floating IPs. Only networks with this flag may be an external gateway for routers. The network must have an external routing facility that is not managed by the networking service. If the network is updated from external to internal the unused floating IPs of this network are automatically deleted when extension floatingip-autodelete-internal is present.

segments

body

array

A list of provider segment objects.

shared

body

boolean

Indicates whether this network is shared across all tenants. By default, only administrative users can change this value.

status

body

string

The network status. Values are ACTIVE, DOWN, BUILD or ERROR.

subnets

body

array

The associated subnets.

tenant_id

body

string

The ID of the project.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

vlan_transparent

body

boolean

Indicates the VLAN transparency mode of the network, which is VLAN transparent (true) or not VLAN transparent (false).

description

body

string

A human-readable description for the resource.

is_default

body

boolean

The network is default pool or not.

tags

body

array

The list of tags on the resource.

Response Example

{
    "networks": [
        {
            "admin_state_up": true,
            "availability_zone_hints": [],
            "availability_zones": [
                "nova"
            ],
            "created_at": "2016-03-08T20:19:41",
            "dns_domain": "",
            "id": "bc1a76cb-8767-4c3a-bb95-018b822f2130",
            "ipv4_address_scope": null,
            "ipv6_address_scope": null,
            "l2_adjacency": true,
            "mtu": 1500,
            "name": "sample_network3",
            "project_id": "4fd44f30292945e481c7b8a0c8908869",
            "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e",
            "revision_number": 1,
            "router:external": false,
            "shared": false,
            "status": "ACTIVE",
            "subnets": [],
            "tags": ["tag1,tag2"],
            "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
            "updated_at": "2016-03-08T20:19:41",
            "vlan_transparent": false,
            "description": "",
            "port_security_enabled": true,
            "is_default": false
        },
        {
            "admin_state_up": true,
            "availability_zone_hints": [],
            "availability_zones": [
                "nova"
            ],
            "created_at": "2016-03-08T20:19:41",
            "dns_domain": "",
            "id": "af374017-c9ae-4a1d-b799-ab73111476e2",
            "ipv4_address_scope": null,
            "ipv6_address_scope": null,
            "l2_adjacency": true,
            "mtu": 1500,
            "name": "sample_network4",
            "project_id": "4fd44f30292945e481c7b8a0c8908869",
            "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e",
            "revision_number": 1,
            "router:external": false,
            "shared": false,
            "status": "ACTIVE",
            "subnets": [],
            "tags": ["tag1,tag2"],
            "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
            "updated_at": "2016-03-08T20:19:41",
            "vlan_transparent": false,
            "description": "",
            "port_security_enabled": true,
            "is_default": false
        }
    ]
}

Network Segment Ranges

The network segment range extension exposes the segment range management to be administered via the Neutron API. It introduces the network-segment-range resource for tenant network segment allocation. In addition, it introduces the ability for the administrator to control the segment ranges globally or on a per-tenant basis.

Lists, shows details for, creates, updates, and deletes network segment ranges. The network segment ranges API is admin-only.

Resource timestamps

The standard-attr-timestamp extension adds the created_at and updated_at attributes to all resources that have standard attributes.

Tag extension

The standard-attr-tag adds tag support for resources with standard attributes by adding the tags attribute allowing consumers to associate tags with resources.

GET
/v2.0/network_segment_ranges/{network_segment_range_id}

Show network segment range details

Shows details for a network segment range.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

network_segment_range_id

path

string

The ID of the network segment range.

Response Parameters

Name

In

Type

Description

id

body

string

The UUID of the network segment range.

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

default

body

boolean

Defines whether the network segment range is the default that is loaded from the host ML2 config file.

shared

body

boolean

Indicates whether this network segment range is shared across all projects.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

network_type

body

string

The type of physical network that maps to this network segment range resource. For example, vlan, vxlan, or gre. Valid values depend on a networking back-end.

physical_network

body

string

The physical network where this network segment range is implemented.

minimum

body

integer

The minimum segmentation ID of the network segment range.

maximum

body

integer

The maximum segmentation ID of the network segment range.

available

body

list

List of available segmentation IDs in the network segment range.

used

body

dict

Mapping of which segmentation ID in the network segment range is used by which project.

revision_number

body

integer

The revision number of the resource.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

tags

body

array

The list of tags on the resource.

Response Example

{
    "network_segment_range": {
        "id": "59b38ee8-6642-418a-88b7-756861606ecb",
        "name": "range_vlan_physnet1",
        "description": "network segment range for testing",
        "default": false,
        "shared": false,
        "tenant_id": "7011dc7fccac4efda89dc3b7f0d0975a",
        "project_id": "7011dc7fccac4efda89dc3b7f0d0975a",
        "network_type": "vlan",
        "physical_network": "physnet1",
        "minimum": 10,
        "maximum": 20,
        "available": [10,11,12,13,14,15,16,19,20],
        "used": {
            "17": "5fc1cd2f16ab4c8fbba2e780891b9de3",
            "18": "87504c1c9d86439882ff90fdbfb096ad"}
        },
        "created_at": "2019-03-04T04:49:28Z",
        "updated_at": "2019-03-04T04:49:28Z",
        "revision_number": 1,
        "tags": ["tag1,tag2"]
}
PUT
/v2.0/network_segment_ranges/{network_segment_range_id}

Update network segment range

Updates a network segment range.

Normal response codes: 200

Error response codes: 400, 401, 403, 404, 412

Request

Name

In

Type

Description

network_segment_range_id

path

string

The ID of the network segment range.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

minimum (Optional)

body

integer

The minimum segmentation ID of the network segment range.

maximum (Optional)

body

integer

The maximum segmentation ID of the network segment range.

tags (Optional)

query

string

A list of tags to filter the list result by. Resources that match all tags in this list will be returned. Tags in query must be separated by comma.

tags-any (Optional)

query

string

A list of tags to filter the list result by. Resources that match any tag in this list will be returned. Tags in query must be separated by comma.

not-tags (Optional)

query

string

A list of tags to filter the list result by. Resources that match all tags in this list will be excluded. Tags in query must be separated by comma.

not-tags-any (Optional)

query

string

A list of tags to filter the list result by. Resources that match any tag in this list will be excluded. Tags in query must be separated by comma.

Request Example

{
    "network_segment_range": {
        "name": "new_range",
        "minimum": 10,
        "maximum": 20,
        "description": "network segment range updated for testing"
    }
}

Response Parameters

Name

In

Type

Description

id

body

string

The UUID of the network segment range.

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

default

body

boolean

Defines whether the network segment range is the default that is loaded from the host ML2 config file.

shared

body

boolean

Indicates whether this network segment range is shared across all projects.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

network_type

body

string

The type of physical network that maps to this network segment range resource. For example, vlan, vxlan, or gre. Valid values depend on a networking back-end.

physical_network

body

string

The physical network where this network segment range is implemented.

minimum

body

integer

The minimum segmentation ID of the network segment range.

maximum

body

integer

The maximum segmentation ID of the network segment range.

available

body

list

List of available segmentation IDs in the network segment range.

used

body

dict

Mapping of which segmentation ID in the network segment range is used by which project.

revision_number

body

integer

The revision number of the resource.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

tags

body

array

The list of tags on the resource.

Response Example

{
    "network_segment_range": {
        "id": "50089a13-4a9f-4421-85ba-5222e84610c3",
        "name": "new_range",
        "description": "network segment range updated for testing",
        "default": false,
        "shared": false,
        "tenant_id": "7011dc7fccac4efda89dc3b7f0d0975a",
        "project_id": "7011dc7fccac4efda89dc3b7f0d0975a",
        "network_type": "vxlan",
        "physical_network": null,
        "minimum": 10,
        "maximum": 20,
        "available": [10,11,12,13,14,15,16,19,20],
        "used": {
            "17": "5fc1cd2f16ab4c8fbba2e780891b9de3",
            "18": "87504c1c9d86439882ff90fdbfb096ad"},
        "created_at": "2019-03-04T04:56:49Z",
        "updated_at": "2019-03-04T04:58:06Z",
        "revision_number": 2,
        "tags": ["tag1,tag2"]
    }
}
DELETE
/v2.0/network_segment_ranges/{network_segment_range_id}

Delete network segment range

Deletes a network segment range.

Normal response codes: 204

Error response codes: 401, 404, 409, 412

Request

Name

In

Type

Description

network_segment_range_id

path

string

The ID of the network segment range.

Response

There is no body content for the response of a successful DELETE request.

GET
/v2.0/network_segment_ranges

List network segment ranges

Lists network segment ranges to which the admin has access.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

id (Optional)

query

string

Filter the network segment range list result based on the range ID.

name (Optional)

query

string

Filter the network segment range list result based on the name of the range.

tenant_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

project_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

network_type (Optional)

query

string

Filter the list result by the type of physical network that this network segment range is mapped to. For example, vlan, vxlan, or gre. Valid values depend on a networking back-end.

physical_network (Optional)

query

string

Filter the list result by the physical network where this network segment range is implemented.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a network segment range attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • id

  • name

  • project_id

  • tenant_id

tags (Optional)

query

string

A list of tags to filter the list result by. Resources that match all tags in this list will be returned. Tags in query must be separated by comma.

tags-any (Optional)

query

string

A list of tags to filter the list result by. Resources that match any tag in this list will be returned. Tags in query must be separated by comma.

not-tags (Optional)

query

string

A list of tags to filter the list result by. Resources that match all tags in this list will be excluded. Tags in query must be separated by comma.

not-tags-any (Optional)

query

string

A list of tags to filter the list result by. Resources that match any tag in this list will be excluded. Tags in query must be separated by comma.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

id

body

string

The UUID of the network segment range.

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

default

body

boolean

Defines whether the network segment range is the default that is loaded from the host ML2 config file.

shared

body

boolean

Indicates whether this network segment range is shared across all projects.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

network_type

body

string

The type of physical network that maps to this network segment range resource. For example, vlan, vxlan, or gre. Valid values depend on a networking back-end.

physical_network

body

string

The physical network where this network segment range is implemented.

minimum

body

integer

The minimum segmentation ID of the network segment range.

maximum

body

integer

The maximum segmentation ID of the network segment range.

available

body

list

List of available segmentation IDs in the network segment range.

used

body

dict

Mapping of which segmentation ID in the network segment range is used by which project.

revision_number

body

integer

The revision number of the resource.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

tags

body

array

The list of tags on the resource.

Response Example

{
    "network_segment_ranges": [
        {
            "id": "59b38ee8-6642-418a-88b7-756861606ecb",
            "name": "range_vlan_physnet1",
            "description": "network segment range 1 for testing",
            "default": false,
            "shared": false,
            "tenant_id": "7011dc7fccac4efda89dc3b7f0d0975a",
            "project_id": "7011dc7fccac4efda89dc3b7f0d0975a",
            "network_type": "vlan",
            "physical_network": "physnet1",
            "minimum": 10,
            "maximum": 20,
            "available": [10,11,12,13,14,15,16,19,20],
            "used": {
                "17": "5fc1cd2f16ab4c8fbba2e780891b9de3",
                "18": "87504c1c9d86439882ff90fdbfb096ad"},
            "created_at": "2019-03-04T04:49:28Z",
            "updated_at": "2019-03-04T04:49:28Z",
            "revision_number": 1,
            "tags": ["tag1,tag2"]
        },
        {
            "id": "91ea6e31-3a6d-4541-8432-b49b4cacf893",
            "name": "range_vxlan",
            "description": "network segment range 2 for testing",
            "default": false,
            "shared": true,
            "tenant_id": null,
            "project_id": null,
            "network_type": "vxlan",
            "physical_network": null,
            "minimum": 40,
            "maximum": 50,
            "available": [40,41,43,44,46,47,48,49,50],
            "used": {
                "42": "07ac1127ee9647d48ce2626867104a13",
                "45": "d4fa62aa47d340d98d076801aa7e6ec4"},
            "created_at": "2019-03-04T04:56:49Z",
            "updated_at": "2019-03-04T04:58:06Z",
            "revision_number": 2,
            "tags": ["tag1,tag2"]
        }
    ]
}
POST
/v2.0/network_segment_ranges

Create network segment range

Creates a network segment range.

Normal response codes: 201

Error response codes: 400, 401

Request

Name

In

Type

Description

name (Optional)

body

string

Human-readable name of the network segment range.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

shared

body

boolean

Indicates whether this network segment range is shared across all projects.

project_id (Optional)

body

string

The ID of the project that owns the resource.

network_type

body

string

The type of physical network that maps to this network segment range resource. For example, vlan, vxlan, or gre. Valid values depend on a networking back-end.

physical_network (Optional)

body

string

The physical network where this network segment range is implemented.

minimum

body

integer

The minimum segmentation ID of the network segment range.

maximum

body

integer

The minimum segmentation ID of the network segment range.

Request Example

{
    "network_segment_range": {
        "name": "range_vlan_physnet1",
        "description": "network segment range for testing",
        "shared": false,
        "project_id": "7011dc7fccac4efda89dc3b7f0d0975a",
        "network_type": "vlan",
        "physical_network": "physnet1",
        "minimum": 10,
        "maximum": 20
    }
}

Response Parameters

Name

In

Type

Description

id

body

string

The UUID of the network segment range.

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

default

body

boolean

Defines whether the network segment range is the default that is loaded from the host ML2 config file.

shared

body

boolean

Indicates whether this network segment range is shared across all projects.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

network_type

body

string

The type of physical network that maps to this network segment range resource. For example, vlan, vxlan, or gre. Valid values depend on a networking back-end.

physical_network

body

string

The physical network where this network segment range is implemented.

minimum

body

integer

The minimum segmentation ID of the network segment range.

maximum

body

integer

The maximum segmentation ID of the network segment range.

available

body

list

List of available segmentation IDs in the network segment range.

used

body

dict

Mapping of which segmentation ID in the network segment range is used by which project.

revision_number

body

integer

The revision number of the resource.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

tags

body

array

The list of tags on the resource.

Response Example

{
    "network_segment_range": {
        "id": "59b38ee8-6642-418a-88b7-756861606ecb",
        "name": "range_vlan_physnet1",
        "description": "network segment range for testing",
        "default": false,
        "shared": false,
        "tenant_id": "7011dc7fccac4efda89dc3b7f0d0975a",
        "project_id": "7011dc7fccac4efda89dc3b7f0d0975a",
        "network_type": "vlan",
        "physical_network": "physnet1",
        "minimum": 10,
        "maximum": 20,
        "available": [10,11,12,13,14,15,16,17,18,19,20],
        "used": {},
        "created_at": "2019-03-04T04:49:28Z",
        "updated_at": "2019-03-04T04:49:28Z",
        "revision_number": 1,
        "tags": ["tag1,tag2"]
    }
}

Ports

Lists, shows details for, creates, updates, and deletes ports.

Allowed address pairs

The allowed-address-pairs extension adds an allowed_address_pairs attribute to ports. The value of allowed_address_pairs is an array of allowed address pair objects, each having an ip_address and a mac_address. The set of allowed address pairs defines IP and MAC address that the port can use when sending packets if port_security_enabled is true (see the port-security extension). Note that while the ip_address is required in each allowed address pair, the mac_address is optional and will be taken from the port if not specified.

Warning

If a security group with a remote_group_id rule is used by a port, adding an address pair with IP address 0.0.0.0/0 (ANY) will bypass all rules with source IP address restrictions for all ports which use the same security group.

Allowed address pairs (atomic) extension

The Allowed address pairs (atomic) extension (allowedaddresspairs-atomic) extends the port resource by adding two member actions (add_allowed_address_pairs/ remove_allowed_address_pairs) to edit the set of Allowed address pairs atomically on the server side.

Data plane status extension

The data plane port extension (data-plane-status) adds a new attribute data_plane_status to represent the status of the underlying data plane. This attribute is to be managed by entities outside of the Networking service, while the status attribute is managed by Networking service. Both status attributes are independent from one another.

Supported data plane status values:

  • null: no status being reported; default value

  • ACTIVE: the underlying data plane is up and running

  • DOWN: no traffic can flow from/to the port

DNS integration

The dns-integration extension adds the dns_name and dns_assignment attributes to port resources. While the dns_name can be set on create and update operations, the dns_assignment is read-only and shows the hostname, ip_address and fqdn for the port’s internal DNS assignment.

To enable the dns_domain on port resources, the dns-domain-ports extension must be used in conjunction with the dns-integration extension. When enabled and set, a port level dns_domain take precedence over a dns_domain specified in the port’s network allowing per-port DNS domains.

Device profile

The port device profile extension (port-device-profile) defines a named set of user requirements for one or more acceletators. This parameter is a reference for Cyborg project, read by Nova when a port is requested. If this parameter is populated, Nova makes a request to Cyborg. https://docs.openstack.org/api-ref/accelerator/#device-profiles

Extra DHCP option (extra_dhcp_opt) extension

The extra DHCP option (extra_dhcp_opt) extension enables extra DHCP configuration options on ports. For example, PXE boot options to DHCP clients can be specified (e.g. tftp-server, server-ip-address, bootfile-name). The value of the extra_dhcp_opt attribute is an array of DHCP option objects, where each object contains an opt_name and opt_value (string values) as well as an optional ip_version (the acceptable values are either the integer 4 or 6).

IP allocation extension

The IP allocation extension (ip_allocation) adds a new read-only attribute ip_allocation that indicates when ports use deferred, immediate or no IP allocation.

IP Substring Filtering

The ip-substring-filtering extension adds support for filtering ports by using part of an IP address.

Mac learning extension

The mac_learning_enabled extension extends neutron ports providing the ability to enable MAC learning on the associated port via the `mac_learning_enabled` attribute.

NUMA affinity policy

The NUMA affinity policy extension (port-numa-affinity-policy) defines the Nova scheduling strategy according to the network backend NUMA topology. This parameter could be required, preferred, legacy, socket or None.

Port binding extended attributes

The port binding extension (binding) allows administrative users to specify and retrieve physical binding information of ports. The extension defines several attributes whose names have a prefix binding: including binding:host_id, binding:vnic_type, binding:vif_type, binding:vif_details, and binding:profile.

Warning

When new defaults for the API policies are enabled (enforce_new_defaults set to True in the Neutron’s configuration), binding:profile can be set or updated only by the user with granted SERVICE role. In case when it needs to be set by admin user e.g. for debugging purpose, default API policies for create_port:binding:profile and/or update_port:binding:profile needs to be overwritten in the policy.yaml file.

Port hints

The port hints extension (port-hints) introduces the hints port attribute. Hints are backend specific pieces of information, mainly to allow backend specific performance tuning. In itself this extension defines no particular hint, and therefore no valid values of the hints attribute. It just serves as the base for other extensions introducing concrete hints and signals the presence of the hints port attribute to the API user. By default policy, use of the hints attribute is restricted to admininstrative users.

Port hint: Open vSwitch Tx steering

The port-hint-ovs-tx-steering extension allows new values (i.e. a hint) in the hints port attribute. It allows the control of Open vSwitch’s Userspace Tx packet steering options. For Open vSwitch details please see: https://docs.openvswitch.org/en/latest/topics/userspace-tx-steering/

Port resource request

The port resource request extension (port-resource-request) allows administrative users (including Nova) to retrieve the Placement resources and traits needed by a port by introducing the resource_request to port resources.

Port resource request groups

The port resource request groups extension (port-resource-request-groups) introduces a new format of resource_request field for port resource. The new structure enables Neutron to request multiple groups of resources and traits from the same RP subtree.

Resource request new format example

{
    "request_groups": [
        {
            "id": "1e4f3958-c0c9-4dec-82fa-ed2dc1c5cb34",
            "required": ["CUSTOM_VNIC_TYPE_NORMAL"],
            "resources": {
                "NET_PACKET_RATE_KILOPACKET_PER_SEC": 1000
            }
        },
        {
            "id": "b20bb47f-5d6d-45a6-8fe7-2c1b44f0db73",
            "required": ["CUSTOM_PHYSNET_PUBLIC", "CUSTOM_VNIC_TYPE_NORMAL"],
            "resources": {
                "NET_BW_EGR_KILOBIT_PER_SEC": 2000
            }
        }
    ],
    "same_subtree": [
        "1e4f3958-c0c9-4dec-82fa-ed2dc1c5cb34",
        "b20bb47f-5d6d-45a6-8fe7-2c1b44f0db73"
    ]
}

Port security

The port-security extension adds the port_security_enabled boolean attribute to ports. If a port-security value is not specified during port creation, a port will inherit the port_security_enabled from the network its connected to.

Trusted VIF

The port-trusted-vif extension adds trusted attribute to the port resource. This attribute stores information about if SR-IOV port should be trusted. It will be populated in the port binding profile information as the trusted field.

Tag Ports During Bulk Creation

The tag-ports-during-bulk-creation extension adds the ability to set tags for ports when they are created, directly in the POST request. It can be done both when one port is created as well as when ports are created in bulk.

QoS extension

The QoS extension (qos) makes it possible to define QoS policies and associate these to the ports by introducing the qos_policy_id attribute. The policies should be created before they are associated to the ports.

QoS network policy

The qos-port-network-policy extension adds the read only parameter qos_network_policy_id to the port responses. This parameter contains the QoS policy ID of the network where this port is plugged.

Regenerate mac address extension

The Port MAC address regenerate extension (port-mac-address-regenerate) makes it possible to regenerate the mac address of a port. When passing 'null' (None) as the mac_address on port update, a new mac address will be generated and set on the port.

Resource timestamps

The standard-attr-timestamp extension adds the created_at and updated_at attributes to all resources that have standard attributes.

Tag extension

The standard-attr-tag adds Tag support for resources with standard attributes by adding the tags attribute allowing consumers to associate tags with resources.

Hardware offload extension

The port-hardware-offload extension adds hardware_offload_type attribute to the port resource. This attribute stores the type of hardware offload the port is going to use and will be populated in the port binding profile information with “‘capabilities’: [<hardware_offload_type>]”.

GET
/v2.0/ports/{port_id}

Show port details

Shows details for a port.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

port_id

path

string

The ID of the port.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

port

body

object

A port object.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

allowed_address_pairs

body

array

A set of zero or more allowed address pair objects each where address pair object contains an ip_address and mac_address. While the ip_address is required, the mac_address will be taken from the port if not specified. The value of ip_address can be an IP Address or a CIDR (if supported by the underlying extension plugin). A server connected to the port can send a packet with source address which matches one of the specified allowed address pairs.

binding:host_id

body

string

The ID of the host where the port resides.

binding:profile

body

object

A dictionary that enables the application running on the specific host to pass and receive vif port information specific to the networking back-end. The networking API does not define a specific format of this field. If the update request is null this response field will be {}.

binding:vif_details

body

object

A dictionary which contains additional information on the port. Currently the following fields are defined: port_filter and ovs_hybrid_plug. port_filter is a boolean indicating the networking service provides port filtering features such as security group and/or anti MAC/IP spoofing. ovs_hybrid_plug is a boolean used to inform an API consumer like nova that the hybrid plugging strategy for OVS should be used.

binding:vif_type

body

string

The type of which mechanism is used for the port. An API consumer like nova can use this to determine an appropriate way to attach a device (for example an interface of a virtual server) to the port. Available values currently defined includes ovs, bridge, macvtap, hw_veb, hostdev_physical, vhostuser, distributed and other. There are also special values: unbound and binding_failed. unbound means the port is not bound to a networking back-end. binding_failed means an error that the port failed to be bound to a networking back-end.

binding:vnic_type

body

string

The type of vNIC which this port should be attached to. This is used to determine which mechanism driver(s) to be used to bind the port. The valid values are normal, macvtap, direct, baremetal, direct-physical, virtio-forwarder, smart-nic and remote-managed. What type of vNIC is actually available depends on deployments.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

data_plane_status

body

string

Status of the underlying data plane of a port.

description

body

string

A human-readable description for the resource.

device_id

body

string

The ID of the device that uses this port. For example, a server instance or a logical router.

device_owner

body

string

The entity type that uses this port. For example, compute:nova (server instance), network:dhcp (DHCP agent) or network:router_interface (router interface).

dns_assignment

body

object

Data assigned to a port by the Networking internal DNS including the hostname, ip_address and fqdn.

dns_domain

body

string

A valid DNS domain.

dns_name

body

string

A valid DNS name.

extra_dhcp_opts

body

array

A set of zero or more extra DHCP option pairs. An option pair consists of an option value and name.

fixed_ips

body

array

The IP addresses for the port. If the port has multiple IP addresses, this field has multiple entries. Each entry consists of IP address (ip_address) and the subnet ID from which the IP address is assigned (subnet_id).

hints

body

object

Admin-only. The following values control Open vSwitch’s Userspace Tx packet steering feature:

  • {"openvswitch": {"other_config": {"tx-steering": "hash|thread"}}}

id

body

string

The ID of the resource.

ip_allocation

body

string

Indicates when ports use either deferred, immediate or no IP allocation (none).

mac_address

body

string

The MAC address of the port. If the port uses the direct-physical vnic_type then the value of this field is overwritten with the MAC address provided in the active binding:profile if any.

name

body

string

Human-readable name of the resource.

network_id

body

string

The ID of the attached network.

numa_affinity_policy (Optional)

body

string

The port NUMA affinity policy requested during the virtual machine scheduling. Values: None, required, preferred or legacy.

port_security_enabled

body

boolean

The port security status. A valid value is enabled (true) or disabled (false). If port security is enabled for the port, security group rules and anti-spoofing rules are applied to the traffic on the port. If disabled, no such rules are applied.

project_id

body

string

The ID of the project.

qos_network_policy_id

body

string

The ID of the QoS policy of the network where this port is plugged.

qos_policy_id

body

string

The ID of the QoS policy associated with the port.

revision_number

body

integer

The revision number of the resource.

resource_request (Optional)

body

object

Expose Placement resources (i.e.: minimum-bandwidth) and traits (i.e.: vnic-type, physnet) requested by a port to Nova and Placement. A resource_request object contains request_groups and same_subtree keys. request_groups is a list of dicts, where each dict represents one group of resources and traits that needs to be fulfilled from a single resource provider. Every dict in the list must contain id, required and resources keys. The id field is a string which represents a unique UUID that is generated for each group by combining the port_id and UUIDs of the QoS rules contributing to the group via the UUID5 method. required key contains the traits (generated from the vnic_type and the physnet) required by the port, and a resources key contains a mapping of requested resource class name and requested amount from the QoS policy. same_subtree key contains a list of id values from every resource group.

security_groups

body

array

The IDs of security groups applied to the port.

status

body

string

The port status. Values are ACTIVE, DOWN, BUILD and ERROR.

tags

body

array

The list of tags on the resource.

tenant_id

body

string

The ID of the project.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

propagate_uplink_status

body

boolean

The uplink status propagation of the port. Valid values are enabled (true) and disabled (false).

mac_learning_enabled (Optional)

body

boolean

A boolean value that indicates if MAC Learning is enabled on the associated port.

port_trusted_vif

body

boolean

The port’s trusted VIF status. A valid value is true or false. Value of this field is included in the binding:profile dict of the port.

Response Example

{
    "port": {
        "admin_state_up": true,
        "allowed_address_pairs": [],
        "created_at": "2016-03-08T20:19:41",
        "data_plane_status": "ACTIVE",
        "description": "",
        "device_id": "5e3898d7-11be-483e-9732-b2f5eccd2b2e",
        "device_owner": "network:router_interface",
        "dns_assignment": [
            {
                "hostname": "myport",
                "ip_address": "10.0.0.1",
                "fqdn": "myport.my-domain.org"
            }
        ],
        "dns_domain": "my-domain.org.",
        "dns_name": "myport",
        "extra_dhcp_opts": [
            {
                "opt_value": "pxelinux.0",
                "ip_version": 4,
                "opt_name": "bootfile-name"
            }
        ],
        "fixed_ips": [
            {
                "ip_address": "10.0.0.1",
                "subnet_id": "a0304c3a-4f08-4c43-88af-d796509c97d2"
            }
        ],
        "id": "46d4bfb9-b26e-41f3-bd2e-e6dcc1ccedb2",
        "ip_allocation": "immediate",
        "mac_address": "fa:16:3e:23:fd:d7",
        "name": "",
        "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7",
        "port_security_enabled": false,
        "project_id": "7e02058126cc4950b75f9970368ba177",
        "revision_number": 1,
        "security_groups": [],
        "status": "ACTIVE",
        "tags": ["tag1,tag2"],
        "tenant_id": "7e02058126cc4950b75f9970368ba177",
        "updated_at": "2016-03-08T20:19:41",
        "qos_network_policy_id": "174dd0c1-a4eb-49d4-a807-ae80246d82f4",
        "qos_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae",
        "propagate_uplink_status": false,
        "hardware_offload_type": ""
    }
}

Response Example (admin user)

{
    "port": {
        "admin_state_up": true,
        "allowed_address_pairs": [],
        "binding:host_id": "devstack",
        "binding:profile": {},
        "binding:vif_details": {
            "ovs_hybrid_plug": true,
            "port_filter": true
        },
        "binding:vif_type": "ovs",
        "binding:vnic_type": "normal",
        "created_at": "2016-03-08T20:19:41",
        "data_plane_status": "ACTIVE",
        "description": "",
        "device_id": "5e3898d7-11be-483e-9732-b2f5eccd2b2e",
        "device_owner": "network:router_interface",
        "dns_assignment": [
            {
                "hostname": "myport",
                "ip_address": "10.0.0.1",
                "fqdn": "myport.my-domain.org"
            }
        ],
        "dns_domain": "my-domain.org.",
        "dns_name": "myport",
        "extra_dhcp_opts": [
            {
                "opt_value": "pxelinux.0",
                "ip_version": 4,
                "opt_name": "bootfile-name"
            }
        ],
        "fixed_ips": [
            {
                "ip_address": "10.0.0.1",
                "subnet_id": "a0304c3a-4f08-4c43-88af-d796509c97d2"
            }
        ],
        "id": "46d4bfb9-b26e-41f3-bd2e-e6dcc1ccedb2",
        "ip_allocation": "immediate",
        "mac_address": "fa:16:3e:23:fd:d7",
        "mac_learning_enabled": false,
        "name": "",
        "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7",
        "port_security_enabled": false,
        "project_id": "7e02058126cc4950b75f9970368ba177",
        "revision_number": 1,
        "security_groups": [],
        "status": "ACTIVE",
        "tags": ["tag1,tag2"],
        "tenant_id": "7e02058126cc4950b75f9970368ba177",
        "updated_at": "2016-03-08T20:19:41",
        "qos_network_policy_id": "174dd0c1-a4eb-49d4-a807-ae80246d82f4",
        "qos_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae",
        "resource_request": {
            "request_groups": [
                {
                    "id": "1e4f3958-c0c9-4dec-82fa-ed2dc1c5cb34",
                    "required": ["CUSTOM_VNIC_TYPE_NORMAL"],
                    "resources": {
                        "NET_PACKET_RATE_KILOPACKET_PER_SEC": 1000
                    }
                },
                {
                    "id": "b20bb47f-5d6d-45a6-8fe7-2c1b44f0db73",
                    "required": [
                        "CUSTOM_PHYSNET_PUBLIC", "CUSTOM_VNIC_TYPE_NORMAL"],
                    "resources": {
                        "NET_BW_EGR_KILOBIT_PER_SEC": 1000
                    }
                }
            ],
            "same_subtree": [
                "1e4f3958-c0c9-4dec-82fa-ed2dc1c5cb34",
                "b20bb47f-5d6d-45a6-8fe7-2c1b44f0db73"
            ]
        },
        "propagate_uplink_status": false,
        "hardware_offload_type": "",
        "trusted": true
    }
}
PUT
/v2.0/ports/{port_id}

Update port

Updates a port.

You can update information for a port, such as its symbolic name and associated IPs. When you update IPs for a port, any previously associated IPs are removed, returned to the respective subnet allocation pools, and replaced by the IPs in the request body. Therefore, this operation replaces the fixed_ip attribute when you specify it in the request body. If the updated IP addresses are not valid or are already in use, the operation fails and the existing IP addresses are not removed from the port.

When you update security groups for a port and the operation succeeds, any associated security groups are removed and replaced by the security groups in the request body. Therefore, this operation replaces the security_groups attribute when you specify it in the request body. If the security groups are not valid, the operation fails and the existing security groups are not removed from the port.

When you update binding:profile of a port with null it is treated as {} in the response.

The binding:vnic_type attribute can be updated on unbound ports only. If the port is already bound, the update operation of the attribute returns the Conflict (409) response code.

Only admins and users with a specific role can update the data plane status (default role: data_plane_integrator).

Normal response codes: 200

Error response codes: 400, 401, 403, 404, 409, 412

Request

Name

In

Type

Description

port_id

path

string

The ID of the port.

port

body

object

A port object.

admin_state_up (Optional)

body

boolean

The administrative state of the resource, which is up (true) or down (false). Default is true.

allowed_address_pairs (Optional)

body

array

A set of zero or more allowed address pair objects each where address pair object contains an ip_address and mac_address. While the ip_address is required, the mac_address will be taken from the port if not specified. The value of ip_address can be an IP Address or a CIDR (if supported by the underlying extension plugin). A server connected to the port can send a packet with source address which matches one of the specified allowed address pairs.

binding:host_id (Optional)

body

string

The ID of the host where the port resides. The default is an empty string.

binding:profile (Optional)

body

object

A dictionary that enables the application running on the specific host to pass and receive vif port information specific to the networking back-end. This field is only meant for machine-machine communication for compute services like Nova, Ironic or Zun to pass information to a Neutron back-end. It should not be used by multiple services concurrently or by cloud end users. The existing counterexamples (capabilities: [switchdev] for Open vSwitch hardware offload and trusted=true for Trusted Virtual Functions) are due to be cleaned up. The networking API does not define a specific format of this field. The default is an empty dictionary. If you update it with null then it is treated like {} in the response. Since the port-mac-address-override extension the device_mac_address field of the binding:profile can be used to provide the MAC address of the physical device a direct-physical port is being bound to. If provided, then the mac_address field of the port resource will be updated to the MAC from the active binding.

binding:vnic_type (Optional)

body

string

The type of vNIC which this port should be attached to. This is used to determine which mechanism driver(s) to be used to bind the port. The valid values are normal, macvtap, direct, baremetal, direct-physical, virtio-forwarder, smart-nic and remote-managed. What type of vNIC is actually available depends on deployments. The default is normal.

data_plane_status (Optional)

body

string

Status of the underlying data plane of a port.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

device_id (Optional)

body

string

The ID of the device that uses this port. For example, a server instance or a logical router.

device_owner (Optional)

body

string

The entity type that uses this port. For example, compute:nova (server instance), network:dhcp (DHCP agent) or network:router_interface (router interface).

dns_domain (Optional)

body

string

A valid DNS domain.

dns_name (Optional)

body

string

A valid DNS name.

extra_dhcp_opts (Optional)

body

array

A set of zero or more extra DHCP option pairs. An option pair consists of an option value and name.

fixed_ips (Optional)

body

array

The IP addresses for the port. If you would like to assign multiple IP addresses for the port, specify multiple entries in this field. Each entry consists of IP address (ip_address) and the subnet ID from which the IP address is assigned (subnet_id).

  • If you specify both a subnet ID and an IP address, OpenStack Networking tries to allocate the IP address on that subnet to the port.

  • If you specify only a subnet ID, OpenStack Networking allocates an available IP from that subnet to the port.

  • If you specify only an IP address, OpenStack Networking tries to allocate the IP address if the address is a valid IP for any of the subnets on the specified network.

hints (Optional)

body

object

Admin-only. A dict, at the top level keyed by mechanism driver aliases (as defined in setup.cfg). To following values can be used to control Open vSwitch’s Userspace Tx packet steering feature:

  • {"openvswitch": {"other_config": {"tx-steering": "hash"}}}

  • {"openvswitch": {"other_config": {"tx-steering": "thread"}}}

If omitted the default is defined by Open vSwitch. The field cannot be longer than 4095 characters.

mac_address (Optional)

body

string

The MAC address of the port. By default, only administrative users and users with advsvc role can change this value.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

numa_affinity_policy (Optional)

body

string

The port NUMA affinity policy requested during the virtual machine scheduling. Values: None, required, preferred or legacy.

port_security_enabled (Optional)

body

boolean

The port security status. A valid value is enabled (true) or disabled (false). If port security is enabled for the port, security group rules and anti-spoofing rules are applied to the traffic on the port. If disabled, no such rules are applied.

propagate_uplink_status

body

boolean

The uplink status propagation of the port. Valid values are enabled (true) and disabled (false).

qos_policy_id (Optional)

body

string

QoS policy associated with the port.

security_groups (Optional)

body

array

The IDs of security groups applied to the port.

mac_learning_enabled (Optional)

body

boolean

A boolean value that indicates if MAC Learning is enabled on the associated port.

port_trusted_vif (Optional)

body

boolean

The port’s trusted VIF status. A valid value is true or false. Value of this field is included in the binding:profile dict of the port.

Request Example

{
    "port": {
        "admin_state_up": true,
        "device_id": "d90a13da-be41-461f-9f99-1dbcf438fdf2",
        "device_owner": "compute:nova",
        "name": "test-for-port-update",
        "qos_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae",
        "propagate_uplink_status": true
    }
}

Request Example (admin user)

{
    "port": {
        "binding:host_id": "test_for_port_update_host",
        "binding:profile": null,
        "device_id": "d90a13da-be41-461f-9f99-1dbcf438fdf2",
        "data_plane_status": "DOWN",
        "device_owner": "compute:nova",
        "qos_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae"
    }
}

Response Parameters

Name

In

Type

Description

port

body

object

A port object.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

allowed_address_pairs

body

array

A set of zero or more allowed address pair objects each where address pair object contains an ip_address and mac_address. While the ip_address is required, the mac_address will be taken from the port if not specified. The value of ip_address can be an IP Address or a CIDR (if supported by the underlying extension plugin). A server connected to the port can send a packet with source address which matches one of the specified allowed address pairs.

binding:host_id

body

string

The ID of the host where the port resides.

binding:profile

body

object

A dictionary that enables the application running on the specific host to pass and receive vif port information specific to the networking back-end. The networking API does not define a specific format of this field. If the update request is null this response field will be {}.

binding:vif_details

body

object

A dictionary which contains additional information on the port. Currently the following fields are defined: port_filter and ovs_hybrid_plug. port_filter is a boolean indicating the networking service provides port filtering features such as security group and/or anti MAC/IP spoofing. ovs_hybrid_plug is a boolean used to inform an API consumer like nova that the hybrid plugging strategy for OVS should be used.

binding:vif_type

body

string

The type of which mechanism is used for the port. An API consumer like nova can use this to determine an appropriate way to attach a device (for example an interface of a virtual server) to the port. Available values currently defined includes ovs, bridge, macvtap, hw_veb, hostdev_physical, vhostuser, distributed and other. There are also special values: unbound and binding_failed. unbound means the port is not bound to a networking back-end. binding_failed means an error that the port failed to be bound to a networking back-end.

binding:vnic_type

body

string

The type of vNIC which this port should be attached to. This is used to determine which mechanism driver(s) to be used to bind the port. The valid values are normal, macvtap, direct, baremetal, direct-physical, virtio-forwarder, smart-nic and remote-managed. What type of vNIC is actually available depends on deployments.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

data_plane_status

body

string

Status of the underlying data plane of a port.

description

body

string

A human-readable description for the resource.

device_id

body

string

The ID of the device that uses this port. For example, a server instance or a logical router.

device_owner

body

string

The entity type that uses this port. For example, compute:nova (server instance), network:dhcp (DHCP agent) or network:router_interface (router interface).

dns_assignment

body

object

Data assigned to a port by the Networking internal DNS including the hostname, ip_address and fqdn.

dns_domain

body

string

A valid DNS domain.

dns_name

body

string

A valid DNS name.

extra_dhcp_opts

body

array

A set of zero or more extra DHCP option pairs. An option pair consists of an option value and name.

fixed_ips

body

array

The IP addresses for the port. If the port has multiple IP addresses, this field has multiple entries. Each entry consists of IP address (ip_address) and the subnet ID from which the IP address is assigned (subnet_id).

hints

body

object

Admin-only. The following values control Open vSwitch’s Userspace Tx packet steering feature:

  • {"openvswitch": {"other_config": {"tx-steering": "hash|thread"}}}

id

body

string

The ID of the resource.

ip_allocation

body

string

Indicates when ports use either deferred, immediate or no IP allocation (none).

mac_address

body

string

The MAC address of the port. If the port uses the direct-physical vnic_type then the value of this field is overwritten with the MAC address provided in the active binding:profile if any.

name

body

string

Human-readable name of the resource.

network_id

body

string

The ID of the attached network.

numa_affinity_policy (Optional)

body

string

The port NUMA affinity policy requested during the virtual machine scheduling. Values: None, required, preferred or legacy.

port_security_enabled

body

boolean

The port security status. A valid value is enabled (true) or disabled (false). If port security is enabled for the port, security group rules and anti-spoofing rules are applied to the traffic on the port. If disabled, no such rules are applied.

project_id

body

string

The ID of the project.

qos_network_policy_id

body

string

The ID of the QoS policy of the network where this port is plugged.

qos_policy_id

body

string

The ID of the QoS policy associated with the port.

revision_number

body

integer

The revision number of the resource.

resource_request (Optional)

body

object

Expose Placement resources (i.e.: minimum-bandwidth) and traits (i.e.: vnic-type, physnet) requested by a port to Nova and Placement. A resource_request object contains request_groups and same_subtree keys. request_groups is a list of dicts, where each dict represents one group of resources and traits that needs to be fulfilled from a single resource provider. Every dict in the list must contain id, required and resources keys. The id field is a string which represents a unique UUID that is generated for each group by combining the port_id and UUIDs of the QoS rules contributing to the group via the UUID5 method. required key contains the traits (generated from the vnic_type and the physnet) required by the port, and a resources key contains a mapping of requested resource class name and requested amount from the QoS policy. same_subtree key contains a list of id values from every resource group.

security_groups

body

array

The IDs of security groups applied to the port.

status

body

string

The port status. Values are ACTIVE, DOWN, BUILD and ERROR.

tags

body

array

The list of tags on the resource.

tenant_id

body

string

The ID of the project.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

propagate_uplink_status

body

boolean

The uplink status propagation of the port. Valid values are enabled (true) and disabled (false).

mac_learning_enabled (Optional)

body

boolean

A boolean value that indicates if MAC Learning is enabled on the associated port.

port_trusted_vif

body

boolean

The port’s trusted VIF status. A valid value is true or false. Value of this field is included in the binding:profile dict of the port.

Response Example

{
    "port": {
        "admin_state_up": true,
        "allowed_address_pairs": [],
        "binding:host_id": "test_for_port_update_host",
        "binding:profile": {},
        "binding:vif_details": {},
        "binding:vif_type": "binding_failed",
        "binding:vnic_type": "normal",
        "created_at": "2016-03-08T20:19:41",
        "data_plane_status": "ACTIVE",
        "description": "",
        "device_id": "d90a13da-be41-461f-9f99-1dbcf438fdf2",
        "device_owner": "compute:nova",
        "dns_assignment": [
            {
                "hostname": "myport",
                "ip_address": "20.20.0.4",
                "fqdn": "myport.my-domain.org"
            }
        ],
        "dns_domain": "my-domain.org.",
        "dns_name": "myport",
        "extra_dhcp_opts": [
            {
                "opt_value": "pxelinux.0",
                "ip_version": 4,
                "opt_name": "bootfile-name"
            }
        ],
        "fixed_ips": [
            {
                "ip_address": "20.20.0.4",
                "subnet_id": "898dec4a-74df-4193-985f-c76721bcc746"
            }
        ],
        "id": "43c831e0-19ce-4a76-9a49-57b57e69428b",
        "ip_allocation": "immediate",
        "mac_address": "fa:16:3e:11:11:5e",
        "name": "test-for-port-update",
        "network_id": "883fc383-5ea1-4c8b-8916-e1ddb0a9f365",
        "project_id": "522eda8d23124b25bf03fe44f1986b74",
        "revision_number": 1,
        "security_groups": [
            "ce0179d6-8a94-4f7c-91c2-f3038e2acbd0"
        ],
        "status": "DOWN",
        "tags": ["tag1,tag2"],
        "tenant_id": "522eda8d23124b25bf03fe44f1986b74",
        "updated_at": "2016-03-08T20:19:41",
        "qos_network_policy_id": "174dd0c1-a4eb-49d4-a807-ae80246d82f4",
        "qos_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae",
        "port_security_enabled": false,
        "hardware_offload_type": "",
        "trusted": true,
        "propagate_uplink_status": true
    }
}

Response Example (admin user)

{
    "port": {
        "admin_state_up": true,
        "allowed_address_pairs": [],
        "binding:host_id": "test_for_port_update_host",
        "binding:profile": {},
        "binding:vif_details": {},
        "binding:vif_type": "binding_failed",
        "binding:vnic_type": "normal",
        "created_at": "2016-03-08T20:19:41",
        "data_plane_status": "DOWN",
        "description": "",
        "device_id": "d90a13da-be41-461f-9f99-1dbcf438fdf2",
        "device_owner": "compute:nova",
        "dns_assignment": [
            {
                "hostname": "myport",
                "ip_address": "20.20.0.4",
                "fqdn": "myport.my-domain.org"
            }
        ],
        "dns_domain": "my-domain.org.",
        "dns_name": "myport",
        "extra_dhcp_opts": [
            {
                "opt_value": "pxelinux.0",
                "ip_version": 4,
                "opt_name": "bootfile-name"
            }
        ],
        "fixed_ips": [
            {
                "ip_address": "20.20.0.4",
                "subnet_id": "898dec4a-74df-4193-985f-c76721bcc746"
            }
        ],
        "id": "43c831e0-19ce-4a76-9a49-57b57e69428b",
        "ip_allocation": "immediate",
        "mac_address": "fa:16:3e:11:11:5e",
        "name": "test-for-port-update",
        "network_id": "883fc383-5ea1-4c8b-8916-e1ddb0a9f365",
        "project_id": "522eda8d23124b25bf03fe44f1986b74",
        "revision_number": 2,
        "security_groups": [
            "ce0179d6-8a94-4f7c-91c2-f3038e2acbd0"
        ],
        "status": "DOWN",
        "tags": ["tag1,tag2"],
        "tenant_id": "522eda8d23124b25bf03fe44f1986b74",
        "updated_at": "2016-03-08T20:19:41",
        "qos_network_policy_id": "174dd0c1-a4eb-49d4-a807-ae80246d82f4",
        "qos_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae",
        "port_security_enabled": false,
        "resource_request": {
            "request_groups": [
                {
                    "id": "1e4f3958-c0c9-4dec-82fa-ed2dc1c5cb34",
                    "required": ["CUSTOM_VNIC_TYPE_NORMAL"],
                    "resources": {
                        "NET_PACKET_RATE_KILOPACKET_PER_SEC": 1000
                    }
                },
                {
                    "id": "b20bb47f-5d6d-45a6-8fe7-2c1b44f0db73",
                    "required": [
                        "CUSTOM_PHYSNET_PUBLIC", "CUSTOM_VNIC_TYPE_NORMAL"],
                    "resources": {
                        "NET_BW_EGR_KILOBIT_PER_SEC": 1000
                    }
                }
            ],
            "same_subtree": [
                "1e4f3958-c0c9-4dec-82fa-ed2dc1c5cb34",
                "b20bb47f-5d6d-45a6-8fe7-2c1b44f0db73"
            ]
        },
        "propagate_uplink_status": false,
        "hardware_offload_type": "",
        "trusted": true
    }
}
DELETE
/v2.0/ports/{port_id}

Delete port

Deletes a port.

Any IP addresses that are associated with the port are returned to the respective subnets allocation pools.

Normal response codes: 204

Error response codes: 401, 403, 404, 412

Request

Name

In

Type

Description

port_id

path

string

The ID of the port.

Response

There is no body content for the response of a successful DELETE request.

GET
/v2.0/ports

List ports

Lists ports to which the user has access.

Default policy settings return only those ports that are owned by the project of the user who submits the request, unless the request is submitted by a user with administrative rights.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

If the ip-substring-filtering extension is enabled, the Neutron API supports IP address substring filtering on the fixed_ips attribute. If you specify an IP address substring (ip_address_substr) in an entry of the fixed_ips attribute, the Neutron API will list all ports that have an IP address matching the substring.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

admin_state_up (Optional)

query

boolean

Filter the list result by the administrative state of the resource, which is up (true) or down (false).

binding:host_id (Optional)

query

string

Filter the port list result by the ID of the host where the port resides.

description (Optional)

query

string

Filter the list result by the human-readable description of the resource.

device_id (Optional)

query

string

Filter the port list result by the ID of the device that uses this port. For example, a server instance or a logical router.

device_owner (Optional)

query

string

Filter the port result list by the entity type that uses this port. For example, compute:nova (server instance), network:dhcp (DHCP agent) or network:router_interface (router interface).

fixed_ips (Optional)

query

array

Filter the port list result by the IP addresses for the port. This field has one or multiple entries. Each entry consists of IP address (ip_address), IP address substring (ip_address_substr) and/or the subnet ID from which the IP address is assigned (subnet_id).

id (Optional)

query

string

Filter the list result by the ID of the resource.

ip_allocation (Optional)

query

string

Filter the port list result based on if the ports use deferred, immediate or no IP allocation (none).

mac_address (Optional)

query

string

Filter the port list result by the MAC address of the port.

name (Optional)

query

string

Filter the list result by the human-readable name of the resource.

network_id (Optional)

query

string

Filter the list result by the ID of the attached network.

project_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

revision_number (Optional)

query

integer

Filter the list result by the revision number of the resource.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a port attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • admin_state_up

  • device_id

  • device_owner

  • id

  • ip_allocation

  • mac_address

  • name

  • network_id

  • project_id

  • status

  • tenant_id

status (Optional)

query

string

Filter the port list result by the port status. Values are ACTIVE, DOWN, BUILD and ERROR.

tenant_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

tags (Optional)

query

string

A list of tags to filter the list result by. Resources that match all tags in this list will be returned. Tags in query must be separated by comma.

tags-any (Optional)

query

string

A list of tags to filter the list result by. Resources that match any tag in this list will be returned. Tags in query must be separated by comma.

not-tags (Optional)

query

string

A list of tags to filter the list result by. Resources that match all tags in this list will be excluded. Tags in query must be separated by comma.

not-tags-any (Optional)

query

string

A list of tags to filter the list result by. Resources that match any tag in this list will be excluded. Tags in query must be separated by comma.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

mac_learning_enabled (Optional)

query

boolean

Filter the list result by the mac_learning_enabled state of the resource, which is enabled (true) or disabled (false).

Response Parameters

Name

In

Type

Description

ports

body

array

A list of port objects.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

allowed_address_pairs

body

array

A set of zero or more allowed address pair objects each where address pair object contains an ip_address and mac_address. While the ip_address is required, the mac_address will be taken from the port if not specified. The value of ip_address can be an IP Address or a CIDR (if supported by the underlying extension plugin). A server connected to the port can send a packet with source address which matches one of the specified allowed address pairs.

binding:host_id

body

string

The ID of the host where the port resides.

binding:profile

body

object

A dictionary that enables the application running on the specific host to pass and receive vif port information specific to the networking back-end. The networking API does not define a specific format of this field. If the update request is null this response field will be {}.

binding:vif_details

body

object

A dictionary which contains additional information on the port. Currently the following fields are defined: port_filter and ovs_hybrid_plug. port_filter is a boolean indicating the networking service provides port filtering features such as security group and/or anti MAC/IP spoofing. ovs_hybrid_plug is a boolean used to inform an API consumer like nova that the hybrid plugging strategy for OVS should be used.

binding:vif_type

body

string

The type of which mechanism is used for the port. An API consumer like nova can use this to determine an appropriate way to attach a device (for example an interface of a virtual server) to the port. Available values currently defined includes ovs, bridge, macvtap, hw_veb, hostdev_physical, vhostuser, distributed and other. There are also special values: unbound and binding_failed. unbound means the port is not bound to a networking back-end. binding_failed means an error that the port failed to be bound to a networking back-end.

binding:vnic_type

body

string

The type of vNIC which this port should be attached to. This is used to determine which mechanism driver(s) to be used to bind the port. The valid values are normal, macvtap, direct, baremetal, direct-physical, virtio-forwarder, smart-nic and remote-managed. What type of vNIC is actually available depends on deployments.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

data_plane_status

body

string

Status of the underlying data plane of a port.

description

body

string

A human-readable description for the resource.

device_id

body

string

The ID of the device that uses this port. For example, a server instance or a logical router.

device_owner

body

string

The entity type that uses this port. For example, compute:nova (server instance), network:dhcp (DHCP agent) or network:router_interface (router interface).

dns_assignment

body

object

Data assigned to a port by the Networking internal DNS including the hostname, ip_address and fqdn.

dns_domain

body

string

A valid DNS domain.

dns_name

body

string

A valid DNS name.

extra_dhcp_opts

body

array

A set of zero or more extra DHCP option pairs. An option pair consists of an option value and name.

fixed_ips

body

array

The IP addresses for the port. If the port has multiple IP addresses, this field has multiple entries. Each entry consists of IP address (ip_address) and the subnet ID from which the IP address is assigned (subnet_id).

hints

body

object

Admin-only. The following values control Open vSwitch’s Userspace Tx packet steering feature:

  • {"openvswitch": {"other_config": {"tx-steering": "hash|thread"}}}

id

body

string

The ID of the resource.

ip_allocation

body

string

Indicates when ports use either deferred, immediate or no IP allocation (none).

mac_address

body

string

The MAC address of the port. If the port uses the direct-physical vnic_type then the value of this field is overwritten with the MAC address provided in the active binding:profile if any.

name

body

string

Human-readable name of the resource.

network_id

body

string

The ID of the attached network.

numa_affinity_policy (Optional)

body

string

The port NUMA affinity policy requested during the virtual machine scheduling. Values: None, required, preferred or legacy.

port_security_enabled

body

boolean

The port security status. A valid value is enabled (true) or disabled (false). If port security is enabled for the port, security group rules and anti-spoofing rules are applied to the traffic on the port. If disabled, no such rules are applied.

project_id

body

string

The ID of the project.

qos_network_policy_id

body

string

The ID of the QoS policy of the network where this port is plugged.

qos_policy_id

body

string

The ID of the QoS policy associated with the port.

revision_number

body

integer

The revision number of the resource.

resource_request (Optional)

body

object

Expose Placement resources (i.e.: minimum-bandwidth) and traits (i.e.: vnic-type, physnet) requested by a port to Nova and Placement. A resource_request object contains request_groups and same_subtree keys. request_groups is a list of dicts, where each dict represents one group of resources and traits that needs to be fulfilled from a single resource provider. Every dict in the list must contain id, required and resources keys. The id field is a string which represents a unique UUID that is generated for each group by combining the port_id and UUIDs of the QoS rules contributing to the group via the UUID5 method. required key contains the traits (generated from the vnic_type and the physnet) required by the port, and a resources key contains a mapping of requested resource class name and requested amount from the QoS policy. same_subtree key contains a list of id values from every resource group.

security_groups

body

array

The IDs of security groups applied to the port.

status

body

string

The port status. Values are ACTIVE, DOWN, BUILD and ERROR.

tags

body

array

The list of tags on the resource.

tenant_id

body

string

The ID of the project.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

propagate_uplink_status

body

boolean

The uplink status propagation of the port. Valid values are enabled (true) and disabled (false).

mac_learning_enabled (Optional)

body

boolean

A boolean value that indicates if MAC Learning is enabled on the associated port.

port_trusted_vif

body

boolean

The port’s trusted VIF status. A valid value is true or false. Value of this field is included in the binding:profile dict of the port.

Response Example

{
    "ports": [
        {
            "admin_state_up": true,
            "allowed_address_pairs": [],
            "created_at": "2016-03-08T20:19:41",
            "data_plane_status": null,
            "description": "",
            "device_id": "9ae135f4-b6e0-4dad-9e91-3c223e385824",
            "device_owner": "network:router_gateway",
            "dns_assignment": [
                {
                    "hostname": "myport",
                    "ip_address": "172.24.4.2",
                    "fqdn": "myport.my-domain.org"
                }
            ],
            "dns_domain": "my-domain.org.",
            "dns_name": "myport",
            "extra_dhcp_opts": [
            {
                "opt_value": "pxelinux.0",
                "ip_version": 4,
                "opt_name": "bootfile-name"
            }
            ],
            "fixed_ips": [
                {
                    "ip_address": "172.24.4.2",
                    "subnet_id": "008ba151-0b8c-4a67-98b5-0d2b87666062"
                }
            ],
            "id": "d80b1a3b-4fc1-49f3-952e-1e2ab7081d8b",
            "ip_allocation": "immediate",
            "mac_address": "fa:16:3e:58:42:ed",
            "name": "",
            "network_id": "70c1db1f-b701-45bd-96e0-a313ee3430b3",
            "project_id": "",
            "revision_number": 1,
            "security_groups": [],
            "status": "ACTIVE",
            "tags": ["tag1,tag2"],
            "tenant_id": "",
            "updated_at": "2016-03-08T20:19:41",
            "qos_network_policy_id": "174dd0c1-a4eb-49d4-a807-ae80246d82f4",
            "qos_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae",
            "port_security_enabled": false,
            "propagate_uplink_status": false
        },
        {
            "admin_state_up": true,
            "allowed_address_pairs": [],
            "created_at": "2016-03-08T20:19:41",
            "data_plane_status": null,
            "description": "",
            "device_id": "9ae135f4-b6e0-4dad-9e91-3c223e385824",
            "device_owner": "network:router_interface",
            "dns_assignment": [
                {
                    "hostname": "myport2",
                    "ip_address": "10.0.0.1",
                    "fqdn": "myport2.my-domain.org"
                }
            ],
            "dns_domain": "my-domain.org.",
            "dns_name": "myport2",
            "extra_dhcp_opts": [
                {
                    "opt_value": "pxelinux.0",
                    "ip_version": 4,
                    "opt_name": "bootfile-name"
                }
            ],
            "fixed_ips": [
                {
                    "ip_address": "10.0.0.1",
                    "subnet_id": "288bf4a1-51ba-43b6-9d0a-520e9005db17"
                }
            ],
            "id": "f71a6703-d6de-4be1-a91a-a570ede1d159",
            "ip_allocation": "immediate",
            "mac_address": "fa:16:3e:bb:3c:e4",
            "name": "",
            "network_id": "f27aa545-cbdd-4907-b0c6-c9e8b039dcc2",
            "project_id": "d397de8a63f341818f198abb0966f6f3",
            "revision_number": 1,
            "security_groups": [],
            "status": "ACTIVE",
            "tags": ["tag1,tag2"],
            "tenant_id": "d397de8a63f341818f198abb0966f6f3",
            "updated_at": "2016-03-08T20:19:41",
            "qos_network_policy_id": null,
            "qos_policy_id": null,
            "port_security_enabled": false,
            "propagate_uplink_status": false
        }
    ]
}

Response Example (admin user)

{
    "ports": [
        {
            "admin_state_up": true,
            "allowed_address_pairs": [],
            "binding:host_id": "devstack",
            "binding:profile": {},
            "binding:vif_details": {
                "ovs_hybrid_plug": true,
                "port_filter": true
            },
            "binding:vif_type": "ovs",
            "binding:vnic_type": "normal",
            "created_at": "2016-03-08T20:19:41",
            "data_plane_status": null,
            "description": "",
            "device_id": "9ae135f4-b6e0-4dad-9e91-3c223e385824",
            "device_owner": "network:router_gateway",
            "dns_assignment": [
                {
                    "hostname": "myport",
                    "ip_address": "172.24.4.2",
                    "fqdn": "myport.my-domain.org"
                }
            ],
            "dns_domain": "my-domain.org.",
            "dns_name": "myport",
            "extra_dhcp_opts": [],
            "fixed_ips": [
                {
                    "ip_address": "172.24.4.2",
                    "subnet_id": "008ba151-0b8c-4a67-98b5-0d2b87666062"
                }
            ],
            "id": "d80b1a3b-4fc1-49f3-952e-1e2ab7081d8b",
            "ip_allocation": "immediate",
            "mac_address": "fa:16:3e:58:42:ed",
            "name": "",
            "network_id": "70c1db1f-b701-45bd-96e0-a313ee3430b3",
            "port_security_enabled": true,
            "project_id": "",
            "revision_number": 1,
            "security_groups": [],
            "status": "ACTIVE",
            "updated_at": "2016-03-08T20:19:41",
            "qos_network_policy_id": null,
            "qos_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae",
            "resource_request": {
                "request_groups": [
                    {
                        "id": "1e4f3958-c0c9-4dec-82fa-ed2dc1c5cb34",
                        "required": ["CUSTOM_VNIC_TYPE_NORMAL"],
                        "resources": {
                            "NET_PACKET_RATE_KILOPACKET_PER_SEC": 1000
                        }
                    },
                    {
                        "id": "b20bb47f-5d6d-45a6-8fe7-2c1b44f0db73",
                        "required": [
                            "CUSTOM_PHYSNET_PUBLIC", "CUSTOM_VNIC_TYPE_NORMAL"],
                        "resources": {
                            "NET_BW_EGR_KILOBIT_PER_SEC": 1000
                        }
                    }
                ],
                "same_subtree": [
                    "1e4f3958-c0c9-4dec-82fa-ed2dc1c5cb34",
                    "b20bb47f-5d6d-45a6-8fe7-2c1b44f0db73"
                ]
            },
            "tags": ["tag1,tag2"],
            "tenant_id": "",
            "propagate_uplink_status": false,
            "hardware_offload_type": "",
            "trusted": true
        },
        {
            "admin_state_up": true,
            "allowed_address_pairs": [],
            "binding:host_id": "devstack",
            "binding:profile": {},
            "binding:vif_details": {
                "ovs_hybrid_plug": true,
                "port_filter": true
            },
            "binding:vif_type": "ovs",
            "binding:vnic_type": "normal",
            "created_at": "2016-03-08T20:19:41",
            "data_plane_status": null,
            "description": "",
            "device_id": "9ae135f4-b6e0-4dad-9e91-3c223e385824",
            "device_owner": "network:router_interface",
            "dns_assignment": [
                {
                    "hostname": "myport2",
                    "ip_address": "10.0.0.1",
                    "fqdn": "myport2.my-domain.org"
                }
            ],
            "dns_domain": "my-domain.org.",
            "dns_name": "myport2",
            "extra_dhcp_opts": [],
            "fixed_ips": [
                {
                    "ip_address": "10.0.0.1",
                    "subnet_id": "288bf4a1-51ba-43b6-9d0a-520e9005db17"
                }
            ],
            "id": "f71a6703-d6de-4be1-a91a-a570ede1d159",
            "ip_allocation": "immediate",
            "mac_address": "fa:16:3e:bb:3c:e4",
            "name": "",
            "network_id": "f27aa545-cbdd-4907-b0c6-c9e8b039dcc2",
            "port_security_enabled": true,
            "project_id": "d397de8a63f341818f198abb0966f6f3",
            "revision_number": 2,
            "security_groups": [],
            "status": "ACTIVE",
            "updated_at": "2016-03-08T20:19:41",
            "qos_network_policy_id": "174dd0c1-a4eb-49d4-a807-ae80246d82f4",
            "qos_policy_id": null,
            "tags": ["tag1,tag2"],
            "tenant_id": "d397de8a63f341818f198abb0966f6f3",
            "propagate_uplink_status": false,
            "hardware_offload_type": "",
            "trusted": false
        }
    ]
}
POST
/v2.0/ports

Create port

Creates a port on a network.

To define the network in which to create the port, specify the network_id attribute in the request body.

Normal response codes: 201

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

port

body

object

A port object.

admin_state_up (Optional)

body

boolean

The administrative state of the resource, which is up (true) or down (false). Default is true.

allowed_address_pairs (Optional)

body

array

A set of zero or more allowed address pair objects each where address pair object contains an ip_address and mac_address. While the ip_address is required, the mac_address will be taken from the port if not specified. The value of ip_address can be an IP Address or a CIDR (if supported by the underlying extension plugin). A server connected to the port can send a packet with source address which matches one of the specified allowed address pairs.

binding:host_id (Optional)

body

string

The ID of the host where the port resides. The default is an empty string.

binding:profile (Optional)

body

object

A dictionary that enables the application running on the specific host to pass and receive vif port information specific to the networking back-end. This field is only meant for machine-machine communication for compute services like Nova, Ironic or Zun to pass information to a Neutron back-end. It should not be used by multiple services concurrently or by cloud end users. The existing counterexamples (capabilities: [switchdev] for Open vSwitch hardware offload and trusted=true for Trusted Virtual Functions) are due to be cleaned up. The networking API does not define a specific format of this field. The default is an empty dictionary. If you update it with null then it is treated like {} in the response. Since the port-mac-address-override extension the device_mac_address field of the binding:profile can be used to provide the MAC address of the physical device a direct-physical port is being bound to. If provided, then the mac_address field of the port resource will be updated to the MAC from the active binding.

binding:vnic_type (Optional)

body

string

The type of vNIC which this port should be attached to. This is used to determine which mechanism driver(s) to be used to bind the port. The valid values are normal, macvtap, direct, baremetal, direct-physical, virtio-forwarder, smart-nic and remote-managed. What type of vNIC is actually available depends on deployments. The default is normal.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

device_id (Optional)

body

string

The ID of the device that uses this port. For example, a server instance or a logical router.

device_owner (Optional)

body

string

The entity type that uses this port. For example, compute:nova (server instance), network:dhcp (DHCP agent) or network:router_interface (router interface).

dns_domain (Optional)

body

string

A valid DNS domain.

dns_name (Optional)

body

string

A valid DNS name.

extra_dhcp_opts (Optional)

body

array

A set of zero or more extra DHCP option pairs. An option pair consists of an option value and name.

fixed_ips (Optional)

body

array

The IP addresses for the port. If you would like to assign multiple IP addresses for the port, specify multiple entries in this field. Each entry consists of IP address (ip_address) and the subnet ID from which the IP address is assigned (subnet_id).

  • If you specify both a subnet ID and an IP address, OpenStack Networking tries to allocate the IP address on that subnet to the port.

  • If you specify only a subnet ID, OpenStack Networking allocates an available IP from that subnet to the port.

  • If you specify only an IP address, OpenStack Networking tries to allocate the IP address if the address is a valid IP for any of the subnets on the specified network.

hints (Optional)

body

object

Admin-only. A dict, at the top level keyed by mechanism driver aliases (as defined in setup.cfg). To following values can be used to control Open vSwitch’s Userspace Tx packet steering feature:

  • {"openvswitch": {"other_config": {"tx-steering": "hash"}}}

  • {"openvswitch": {"other_config": {"tx-steering": "thread"}}}

If omitted the default is defined by Open vSwitch. The field cannot be longer than 4095 characters.

mac_address (Optional)

body

string

The MAC address of the port. If unspecified, a MAC address is automatically generated.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

network_id

body

string

The ID of the attached network.

numa_affinity_policy (Optional)

body

string

The port NUMA affinity policy requested during the virtual machine scheduling. Values: None, required, preferred or legacy.

port_security_enabled (Optional)

body

boolean

The port security status. A valid value is enabled (true) or disabled (false). If port security is enabled for the port, security group rules and anti-spoofing rules are applied to the traffic on the port. If disabled, no such rules are applied.

project_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

qos_policy_id (Optional)

body

string

QoS policy associated with the port.

security_groups (Optional)

body

array

The IDs of security groups applied to the port.

tenant_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

propagate_uplink_status (Optional)

body

boolean

The uplink status propagation of the port. Valid values are enabled (true) and disabled (false).

mac_learning_enabled (Optional)

body

boolean

A boolean value that indicates if MAC Learning is enabled on the associated port.

port_trusted_vif (Optional)

body

boolean

The port’s trusted VIF status. A valid value is true or false. Value of this field is included in the binding:profile dict of the port.

Request Example

{
    "port": {
        "admin_state_up": true,
        "dns_domain": "my-domain.org.",
        "dns_name": "myport",
        "name": "private-port",
        "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7",
        "qos_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae",
        "port_security_enabled": true,
        "allowed_address_pairs": [
            {
                "ip_address": "12.12.11.12",
                "mac_address": "fa:14:2a:b3:cb:f0"
            }
        ],
        "propagate_uplink_status": false,
        "hardware_offload_type": "",
        "trusted": true
    }
}

Request Example (admin user)

{
    "port": {
        "binding:host_id": "4df8d9ff-6f6f-438f-90a1-ef660d4586ad",
        "binding:profile": {
            "local_link_information": [
                {
                    "port_id": "Ethernet3/1",
                    "switch_id": "0a:1b:2c:3d:4e:5f",
                    "switch_info": "switch1"
                }
            ]
        },
        "binding:vnic_type": "baremetal",
        "device_id": "d90a13da-be41-461f-9f99-1dbcf438fdf2",
        "device_owner": "baremetal:none",
        "dns_domain": "my-domain.org.",
        "dns_name": "myport",
        "hints": {"openvswitch": {"other_config": {"tx-steering": "hash"}}},
        "qos_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae",
        "propagate_uplink_status": false,
        "trusted": true
    }
}

Response Parameters

Name

In

Type

Description

port

body

object

A port object.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

allowed_address_pairs

body

array

A set of zero or more allowed address pair objects each where address pair object contains an ip_address and mac_address. While the ip_address is required, the mac_address will be taken from the port if not specified. The value of ip_address can be an IP Address or a CIDR (if supported by the underlying extension plugin). A server connected to the port can send a packet with source address which matches one of the specified allowed address pairs.

binding:host_id

body

string

The ID of the host where the port resides.

binding:profile

body

object

A dictionary that enables the application running on the specific host to pass and receive vif port information specific to the networking back-end. The networking API does not define a specific format of this field. If the update request is null this response field will be {}.

binding:vif_details

body

object

A dictionary which contains additional information on the port. Currently the following fields are defined: port_filter and ovs_hybrid_plug. port_filter is a boolean indicating the networking service provides port filtering features such as security group and/or anti MAC/IP spoofing. ovs_hybrid_plug is a boolean used to inform an API consumer like nova that the hybrid plugging strategy for OVS should be used.

binding:vif_type

body

string

The type of which mechanism is used for the port. An API consumer like nova can use this to determine an appropriate way to attach a device (for example an interface of a virtual server) to the port. Available values currently defined includes ovs, bridge, macvtap, hw_veb, hostdev_physical, vhostuser, distributed and other. There are also special values: unbound and binding_failed. unbound means the port is not bound to a networking back-end. binding_failed means an error that the port failed to be bound to a networking back-end.

binding:vnic_type

body

string

The type of vNIC which this port should be attached to. This is used to determine which mechanism driver(s) to be used to bind the port. The valid values are normal, macvtap, direct, baremetal, direct-physical, virtio-forwarder, smart-nic and remote-managed. What type of vNIC is actually available depends on deployments.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

data_plane_status

body

string

Status of the underlying data plane of a port.

description

body

string

A human-readable description for the resource.

device_id

body

string

The ID of the device that uses this port. For example, a server instance or a logical router.

device_owner

body

string

The entity type that uses this port. For example, compute:nova (server instance), network:dhcp (DHCP agent) or network:router_interface (router interface).

dns_assignment

body

object

Data assigned to a port by the Networking internal DNS including the hostname, ip_address and fqdn.

dns_domain

body

string

A valid DNS domain.

dns_name

body

string

A valid DNS name.

extra_dhcp_opts

body

array

A set of zero or more extra DHCP option pairs. An option pair consists of an option value and name.

fixed_ips

body

array

The IP addresses for the port. If the port has multiple IP addresses, this field has multiple entries. Each entry consists of IP address (ip_address) and the subnet ID from which the IP address is assigned (subnet_id).

hints

body

object

Admin-only. The following values control Open vSwitch’s Userspace Tx packet steering feature:

  • {"openvswitch": {"other_config": {"tx-steering": "hash|thread"}}}

id

body

string

The ID of the resource.

ip_allocation

body

string

Indicates when ports use either deferred, immediate or no IP allocation (none).

mac_address

body

string

The MAC address of the port. If the port uses the direct-physical vnic_type then the value of this field is overwritten with the MAC address provided in the active binding:profile if any.

name

body

string

Human-readable name of the resource.

network_id

body

string

The ID of the attached network.

numa_affinity_policy (Optional)

body

string

The port NUMA affinity policy requested during the virtual machine scheduling. Values: None, required, preferred or legacy.

port_security_enabled

body

boolean

The port security status. A valid value is enabled (true) or disabled (false). If port security is enabled for the port, security group rules and anti-spoofing rules are applied to the traffic on the port. If disabled, no such rules are applied.

project_id

body

string

The ID of the project.

qos_network_policy_id

body

string

The ID of the QoS policy of the network where this port is plugged.

qos_policy_id

body

string

The ID of the QoS policy associated with the port.

revision_number

body

integer

The revision number of the resource.

resource_request (Optional)

body

object

Expose Placement resources (i.e.: minimum-bandwidth) and traits (i.e.: vnic-type, physnet) requested by a port to Nova and Placement. A resource_request object contains request_groups and same_subtree keys. request_groups is a list of dicts, where each dict represents one group of resources and traits that needs to be fulfilled from a single resource provider. Every dict in the list must contain id, required and resources keys. The id field is a string which represents a unique UUID that is generated for each group by combining the port_id and UUIDs of the QoS rules contributing to the group via the UUID5 method. required key contains the traits (generated from the vnic_type and the physnet) required by the port, and a resources key contains a mapping of requested resource class name and requested amount from the QoS policy. same_subtree key contains a list of id values from every resource group.

security_groups

body

array

The IDs of security groups applied to the port.

status

body

string

The port status. Values are ACTIVE, DOWN, BUILD and ERROR.

tags

body

array

The list of tags on the resource.

tenant_id

body

string

The ID of the project.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

propagate_uplink_status

body

boolean

The uplink status propagation of the port. Valid values are enabled (true) and disabled (false).

mac_learning_enabled (Optional)

body

boolean

A boolean value that indicates if MAC Learning is enabled on the associated port.

port_trusted_vif

body

boolean

The port’s trusted VIF status. A valid value is true or false. Value of this field is included in the binding:profile dict of the port.

Response Example

{
    "port": {
        "admin_state_up": true,
        "allowed_address_pairs": [
            {
                "ip_address": "12.12.11.12",
                "mac_address": "fa:14:2a:b3:cb:f0"
            }
        ],
        "created_at": "2016-03-08T20:19:41",
        "data_plane_status": null,
        "description": "",
        "device_id": "",
        "device_owner": "",
        "dns_assignment": [
            {
                "hostname": "myport",
                "ip_address": "10.0.0.2",
                "fqdn": "myport.my-domain.org"
            }
        ],
        "dns_domain": "my-domain.org.",
        "dns_name": "myport",
        "extra_dhcp_opts": [
            {
                "opt_value": "pxelinux.0",
                "ip_version": 4,
                "opt_name": "bootfile-name"
            }
        ],
        "fixed_ips": [
            {
                "ip_address": "10.0.0.2",
                "subnet_id": "a0304c3a-4f08-4c43-88af-d796509c97d2"
            }
        ],
        "id": "65c0ee9f-d634-4522-8954-51021b570b0d",
        "ip_allocation": "immediate",
        "mac_address": "fa:16:3e:c9:cb:f0",
        "name": "private-port",
        "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7",
        "port_security_enabled": true,
        "project_id": "d6700c0c9ffa4f1cb322cd4a1f3906fa",
        "revision_number": 1,
        "security_groups": [
            "f0ac4394-7e4a-4409-9701-ba8be283dbc3"
        ],
        "status": "DOWN",
        "tags": ["tag1,tag2"],
        "tenant_id": "d6700c0c9ffa4f1cb322cd4a1f3906fa",
        "updated_at": "2016-03-08T20:19:41",
        "qos_network_policy_id": "174dd0c1-a4eb-49d4-a807-ae80246d82f4",
        "qos_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae",
        "propagate_uplink_status": false,
        "hardware_offload_type": "",
        "trusted": true
    }
}

Response Example (admin user)

{
    "port": {
        "admin_state_up": true,
        "allowed_address_pairs": [
            {
                "ip_address": "12.12.11.12",
                "mac_address": "fa:14:2a:b3:cb:f0"
            }
        ],
        "binding:host_id": "4df8d9ff-6f6f-438f-90a1-ef660d4586ad",
        "binding:profile": {
            "local_link_information": [
                {
                    "port_id": "Ethernet3/1",
                    "switch_id": "0a:1b:2c:3d:4e:5f",
                    "switch_info": "switch1"
                }
            ]
        },
        "binding:vif_details": {},
        "binding:vif_type": "unbound",
        "binding:vnic_type": "other",
        "created_at": "2016-03-08T20:19:41",
        "data_plane_status": null,
        "description": "",
        "device_id": "d90a13da-be41-461f-9f99-1dbcf438fdf2",
        "device_owner": "baremetal:none",
        "dns_assignment": [
            {
                "hostname": "myport",
                "ip_address": "10.0.0.2",
                "fqdn": "myport.my-domain.org"
            }
        ],
        "dns_domain": "my-domain.org.",
        "dns_name": "myport",
        "extra_dhcp_opts": [
            {
                "opt_value": "pxelinux.0",
                "ip_version": 4,
                "opt_name": "bootfile-name"
            }
        ],
        "fixed_ips": [
            {
                "ip_address": "10.0.0.2",
                "subnet_id": "a0304c3a-4f08-4c43-88af-d796509c97d2"
            }
        ],
        "hints": {"openvswitch": {"other_config": {"tx-steering": "hash"}}},
        "id": "65c0ee9f-d634-4522-8954-51021b570b0d",
        "ip_allocation": "immediate",
        "mac_address": "fa:16:3e:c9:cb:f0",
        "name": "private-port",
        "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7",
        "project_id": "d6700c0c9ffa4f1cb322cd4a1f3906fa",
        "revision_number": 1,
        "security_groups": [
            "f0ac4394-7e4a-4409-9701-ba8be283dbc3"
        ],
        "status": "DOWN",
        "tags": ["tag1,tag2"],
        "tenant_id": "d6700c0c9ffa4f1cb322cd4a1f3906fa",
        "updated_at": "2016-03-08T20:19:41",
        "qos_network_policy_id": "174dd0c1-a4eb-49d4-a807-ae80246d82f4",
        "qos_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae",
        "port_security_enabled": true,
        "resource_request": {
            "request_groups": [
                {
                    "id": "1e4f3958-c0c9-4dec-82fa-ed2dc1c5cb34",
                    "required": ["CUSTOM_VNIC_TYPE_NORMAL"],
                    "resources": {
                        "NET_PACKET_RATE_KILOPACKET_PER_SEC": 1000
                    }
                },
                {
                    "id": "b20bb47f-5d6d-45a6-8fe7-2c1b44f0db73",
                    "required": [
                        "CUSTOM_PHYSNET_PUBLIC", "CUSTOM_VNIC_TYPE_NORMAL"],
                    "resources": {
                        "NET_BW_EGR_KILOBIT_PER_SEC": 1000
                    }
                }
            ],
            "same_subtree": [
                "1e4f3958-c0c9-4dec-82fa-ed2dc1c5cb34",
                "b20bb47f-5d6d-45a6-8fe7-2c1b44f0db73"
            ]
        },
        "propagate_uplink_status": false,
        "hardware_offload_type": "switchdev",
        "trusted": true
    }
}
POST
/v2.0/ports

Bulk create ports

Creates multiple ports in a single request. Specify a list of ports in the request body.

Guarantees the atomic completion of the bulk operation.

Normal response codes: 201

Error response codes: 400, 401, 403, 404, 409

Request

Name

In

Type

Description

ports

body

array

A list of port objects.

admin_state_up (Optional)

body

boolean

The administrative state of the resource, which is up (true) or down (false). Default is true.

allowed_address_pairs (Optional)

body

array

A set of zero or more allowed address pair objects each where address pair object contains an ip_address and mac_address. While the ip_address is required, the mac_address will be taken from the port if not specified. The value of ip_address can be an IP Address or a CIDR (if supported by the underlying extension plugin). A server connected to the port can send a packet with source address which matches one of the specified allowed address pairs.

binding:host_id (Optional)

body

string

The ID of the host where the port resides. The default is an empty string.

binding:profile (Optional)

body

object

A dictionary that enables the application running on the specific host to pass and receive vif port information specific to the networking back-end. This field is only meant for machine-machine communication for compute services like Nova, Ironic or Zun to pass information to a Neutron back-end. It should not be used by multiple services concurrently or by cloud end users. The existing counterexamples (capabilities: [switchdev] for Open vSwitch hardware offload and trusted=true for Trusted Virtual Functions) are due to be cleaned up. The networking API does not define a specific format of this field. The default is an empty dictionary. If you update it with null then it is treated like {} in the response. Since the port-mac-address-override extension the device_mac_address field of the binding:profile can be used to provide the MAC address of the physical device a direct-physical port is being bound to. If provided, then the mac_address field of the port resource will be updated to the MAC from the active binding.

binding:vnic_type (Optional)

body

string

The type of vNIC which this port should be attached to. This is used to determine which mechanism driver(s) to be used to bind the port. The valid values are normal, macvtap, direct, baremetal, direct-physical, virtio-forwarder, smart-nic and remote-managed. What type of vNIC is actually available depends on deployments. The default is normal.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

device_id (Optional)

body

string

The ID of the device that uses this port. For example, a server instance or a logical router.

device_owner (Optional)

body

string

The entity type that uses this port. For example, compute:nova (server instance), network:dhcp (DHCP agent) or network:router_interface (router interface).

dns_domain (Optional)

body

string

A valid DNS domain.

dns_name (Optional)

body

string

A valid DNS name.

extra_dhcp_opts (Optional)

body

array

A set of zero or more extra DHCP option pairs. An option pair consists of an option value and name.

fixed_ips (Optional)

body

array

The IP addresses for the port. If you would like to assign multiple IP addresses for the port, specify multiple entries in this field. Each entry consists of IP address (ip_address) and the subnet ID from which the IP address is assigned (subnet_id).

  • If you specify both a subnet ID and an IP address, OpenStack Networking tries to allocate the IP address on that subnet to the port.

  • If you specify only a subnet ID, OpenStack Networking allocates an available IP from that subnet to the port.

  • If you specify only an IP address, OpenStack Networking tries to allocate the IP address if the address is a valid IP for any of the subnets on the specified network.

mac_address (Optional)

body

string

The MAC address of the port. If unspecified, a MAC address is automatically generated.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

network_id

body

string

The ID of the attached network.

numa_affinity_policy (Optional)

body

string

The port NUMA affinity policy requested during the virtual machine scheduling. Values: None, required, preferred or legacy.

port_security_enabled (Optional)

body

boolean

The port security status. A valid value is enabled (true) or disabled (false). If port security is enabled for the port, security group rules and anti-spoofing rules are applied to the traffic on the port. If disabled, no such rules are applied.

project_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

qos_policy_id (Optional)

body

string

QoS policy associated with the port.

security_groups (Optional)

body

array

The IDs of security groups applied to the port.

tenant_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

propagate_uplink_status (Optional)

body

boolean

The uplink status propagation of the port. Valid values are enabled (true) and disabled (false).

mac_learning_enabled (Optional)

body

boolean

A boolean value that indicates if MAC Learning is enabled on the associated port.

Request Example

{
    "ports": [
        {
            "admin_state_up": false,
            "name": "sample_port_1",
            "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7",
            "qos_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae"
        },
        {
            "admin_state_up": false,
            "name": "sample_port_2",
            "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7",
            "hardware_offload_type": "switchdev"
        }
    ]
}

Response Parameters

Name

In

Type

Description

ports

body

array

A list of port objects.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

allowed_address_pairs

body

array

A set of zero or more allowed address pair objects each where address pair object contains an ip_address and mac_address. While the ip_address is required, the mac_address will be taken from the port if not specified. The value of ip_address can be an IP Address or a CIDR (if supported by the underlying extension plugin). A server connected to the port can send a packet with source address which matches one of the specified allowed address pairs.

binding:host_id

body

string

The ID of the host where the port resides.

binding:profile

body

object

A dictionary that enables the application running on the specific host to pass and receive vif port information specific to the networking back-end. The networking API does not define a specific format of this field. If the update request is null this response field will be {}.

binding:vif_details

body

object

A dictionary which contains additional information on the port. Currently the following fields are defined: port_filter and ovs_hybrid_plug. port_filter is a boolean indicating the networking service provides port filtering features such as security group and/or anti MAC/IP spoofing. ovs_hybrid_plug is a boolean used to inform an API consumer like nova that the hybrid plugging strategy for OVS should be used.

binding:vif_type

body

string

The type of which mechanism is used for the port. An API consumer like nova can use this to determine an appropriate way to attach a device (for example an interface of a virtual server) to the port. Available values currently defined includes ovs, bridge, macvtap, hw_veb, hostdev_physical, vhostuser, distributed and other. There are also special values: unbound and binding_failed. unbound means the port is not bound to a networking back-end. binding_failed means an error that the port failed to be bound to a networking back-end.

binding:vnic_type

body

string

The type of vNIC which this port should be attached to. This is used to determine which mechanism driver(s) to be used to bind the port. The valid values are normal, macvtap, direct, baremetal, direct-physical, virtio-forwarder, smart-nic and remote-managed. What type of vNIC is actually available depends on deployments.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

data_plane_status

body

string

Status of the underlying data plane of a port.

description

body

string

A human-readable description for the resource.

device_id

body

string

The ID of the device that uses this port. For example, a server instance or a logical router.

device_owner

body

string

The entity type that uses this port. For example, compute:nova (server instance), network:dhcp (DHCP agent) or network:router_interface (router interface).

dns_assignment

body

object

Data assigned to a port by the Networking internal DNS including the hostname, ip_address and fqdn.

dns_domain

body

string

A valid DNS domain.

dns_name

body

string

A valid DNS name.

extra_dhcp_opts

body

array

A set of zero or more extra DHCP option pairs. An option pair consists of an option value and name.

fixed_ips

body

array

The IP addresses for the port. If the port has multiple IP addresses, this field has multiple entries. Each entry consists of IP address (ip_address) and the subnet ID from which the IP address is assigned (subnet_id).

id

body

string

The ID of the resource.

ip_allocation

body

string

Indicates when ports use either deferred, immediate or no IP allocation (none).

mac_address

body

string

The MAC address of the port. If the port uses the direct-physical vnic_type then the value of this field is overwritten with the MAC address provided in the active binding:profile if any.

name

body

string

Human-readable name of the resource.

network_id

body

string

The ID of the attached network.

numa_affinity_policy (Optional)

body

string

The port NUMA affinity policy requested during the virtual machine scheduling. Values: None, required, preferred or legacy.

port_security_enabled

body

boolean

The port security status. A valid value is enabled (true) or disabled (false). If port security is enabled for the port, security group rules and anti-spoofing rules are applied to the traffic on the port. If disabled, no such rules are applied.

project_id

body

string

The ID of the project.

qos_network_policy_id

body

string

The ID of the QoS policy of the network where this port is plugged.

qos_policy_id

body

string

The ID of the QoS policy associated with the port.

revision_number

body

integer

The revision number of the resource.

security_groups

body

array

The IDs of security groups applied to the port.

status

body

string

The port status. Values are ACTIVE, DOWN, BUILD and ERROR.

tags

body

array

The list of tags on the resource.

tenant_id

body

string

The ID of the project.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

propagate_uplink_status

body

boolean

The uplink status propagation of the port. Valid values are enabled (true) and disabled (false).

mac_learning_enabled (Optional)

body

boolean

A boolean value that indicates if MAC Learning is enabled on the associated port.

Response Example

{
    "ports": [
        {
            "admin_state_up": false,
            "allowed_address_pairs": [],
            "created_at": "2016-03-08T20:19:41",
            "data_plane_status": null,
            "description": "",
            "device_id": "",
            "device_owner": "",
            "dns_domain": "",
            "dns_name": "",
            "extra_dhcp_opts": [
                {
                    "opt_value": "pxelinux.0",
                    "ip_version": 4,
                    "opt_name": "bootfile-name"
                }
            ],
            "fixed_ips": [
                {
                    "ip_address": "10.0.0.5",
                    "subnet_id": "a0304c3a-4f08-4c43-88af-d796509c97d2"
                }
            ],
            "id": "94225baa-9d3f-4b93-bf12-b41e7ce49cdb",
            "ip_allocation": "immediate",
            "mac_address": "fa:16:3e:48:b8:9f",
            "name": "sample_port_1",
            "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7",
            "project_id": "d6700c0c9ffa4f1cb322cd4a1f3906fa",
            "revision_number": 1,
            "security_groups": [
                "f0ac4394-7e4a-4409-9701-ba8be283dbc3"
            ],
            "status": "DOWN",
            "tags": ["tag1,tag2"],
            "tenant_id": "d6700c0c9ffa4f1cb322cd4a1f3906fa",
            "updated_at": "2016-03-08T20:19:41",
            "qos_network_policy_id": null,
            "qos_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae",
            "port_security_enabled": false,
            "propagate_uplink_status": false,
            "hardware_offload_type": "",
            "trusted": null
        },
        {
            "admin_state_up": false,
            "allowed_address_pairs": [],
            "created_at": "2016-03-08T20:19:41",
            "data_plane_status": null,
            "description": "",
            "device_id": "",
            "device_owner": "",
            "dns_assignment": [],
            "dns_domain": "",
            "dns_name": "",
            "extra_dhcp_opts": [
                {
                    "opt_value": "pxelinux.0",
                    "ip_version": 4,
                    "opt_name": "bootfile-name"
                }
            ],
            "fixed_ips": [
                {
                    "ip_address": "10.0.0.6",
                    "subnet_id": "a0304c3a-4f08-4c43-88af-d796509c97d2"
                }
            ],
            "id": "235b09e0-63c4-47f1-b221-66ba54c21760",
            "ip_allocation": "immediate",
            "mac_address": "fa:16:3e:f4:73:df",
            "name": "sample_port_2",
            "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7",
            "project_id": "d6700c0c9ffa4f1cb322cd4a1f3906fa",
            "revision_number": 1,
            "security_groups": [
                "f0ac4394-7e4a-4409-9701-ba8be283dbc3"
            ],
            "status": "DOWN",
            "tags": ["tag1,tag2"],
            "tenant_id": "d6700c0c9ffa4f1cb322cd4a1f3906fa",
            "updated_at": "2016-03-08T20:19:41",
            "qos_network_policy_id": "174dd0c1-a4eb-49d4-a807-ae80246d82f4",
            "qos_policy_id": null,
            "port_security_enabled": false,
            "propagate_uplink_status": false,
            "hardware_offload_type": "switchdev",
            "trusted": null
        }
    ]
}
PUT
/v2.0/ports/{port_id}/add_allowed_address_pairs

Add allowed_address_pairs to port

Atomically adds a set of allowed_address_pairs to the port’s already existing allowed_address_pairs.

Normal response codes: 200

Error response codes: 400, 401, 404, 412

Request

Name

In

Type

Description

port_id

path

string

The ID of the port.

port

body

object

A port object.

allowed_address_pairs (Optional)

body

array

A set of zero or more allowed address pair objects each where address pair object contains an ip_address and mac_address. While the ip_address is required, the mac_address will be taken from the port if not specified. The value of ip_address can be an IP Address or a CIDR (if supported by the underlying extension plugin). A server connected to the port can send a packet with source address which matches one of the specified allowed address pairs.

Request Example

{
   "port" : {
        "allowed_address_pairs": [
            {
                "ip_address": "192.168.13.7",
                "mac_address": "fa:16:3e:09:1f:b2"
            }
        ]
   }
}

Response Parameters

Name

In

Type

Description

port

body

object

A port object.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

allowed_address_pairs

body

array

A set of zero or more allowed address pair objects each where address pair object contains an ip_address and mac_address. While the ip_address is required, the mac_address will be taken from the port if not specified. The value of ip_address can be an IP Address or a CIDR (if supported by the underlying extension plugin). A server connected to the port can send a packet with source address which matches one of the specified allowed address pairs.

binding:host_id

body

string

The ID of the host where the port resides.

binding:profile

body

object

A dictionary that enables the application running on the specific host to pass and receive vif port information specific to the networking back-end. The networking API does not define a specific format of this field. If the update request is null this response field will be {}.

binding:vif_details

body

object

A dictionary which contains additional information on the port. Currently the following fields are defined: port_filter and ovs_hybrid_plug. port_filter is a boolean indicating the networking service provides port filtering features such as security group and/or anti MAC/IP spoofing. ovs_hybrid_plug is a boolean used to inform an API consumer like nova that the hybrid plugging strategy for OVS should be used.

binding:vif_type

body

string

The type of which mechanism is used for the port. An API consumer like nova can use this to determine an appropriate way to attach a device (for example an interface of a virtual server) to the port. Available values currently defined includes ovs, bridge, macvtap, hw_veb, hostdev_physical, vhostuser, distributed and other. There are also special values: unbound and binding_failed. unbound means the port is not bound to a networking back-end. binding_failed means an error that the port failed to be bound to a networking back-end.

binding:vnic_type

body

string

The type of vNIC which this port should be attached to. This is used to determine which mechanism driver(s) to be used to bind the port. The valid values are normal, macvtap, direct, baremetal, direct-physical, virtio-forwarder, smart-nic and remote-managed. What type of vNIC is actually available depends on deployments.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

data_plane_status

body

string

Status of the underlying data plane of a port.

description

body

string

A human-readable description for the resource.

device_id

body

string

The ID of the device that uses this port. For example, a server instance or a logical router.

device_owner

body

string

The entity type that uses this port. For example, compute:nova (server instance), network:dhcp (DHCP agent) or network:router_interface (router interface).

dns_assignment

body

object

Data assigned to a port by the Networking internal DNS including the hostname, ip_address and fqdn.

dns_domain

body

string

A valid DNS domain.

dns_name

body

string

A valid DNS name.

extra_dhcp_opts

body

array

A set of zero or more extra DHCP option pairs. An option pair consists of an option value and name.

fixed_ips

body

array

The IP addresses for the port. If the port has multiple IP addresses, this field has multiple entries. Each entry consists of IP address (ip_address) and the subnet ID from which the IP address is assigned (subnet_id).

hints

body

object

Admin-only. The following values control Open vSwitch’s Userspace Tx packet steering feature:

  • {"openvswitch": {"other_config": {"tx-steering": "hash|thread"}}}

id

body

string

The ID of the resource.

ip_allocation

body

string

Indicates when ports use either deferred, immediate or no IP allocation (none).

mac_address

body

string

The MAC address of the port. If the port uses the direct-physical vnic_type then the value of this field is overwritten with the MAC address provided in the active binding:profile if any.

name

body

string

Human-readable name of the resource.

network_id

body

string

The ID of the attached network.

numa_affinity_policy (Optional)

body

string

The port NUMA affinity policy requested during the virtual machine scheduling. Values: None, required, preferred or legacy.

port_security_enabled

body

boolean

The port security status. A valid value is enabled (true) or disabled (false). If port security is enabled for the port, security group rules and anti-spoofing rules are applied to the traffic on the port. If disabled, no such rules are applied.

project_id

body

string

The ID of the project.

qos_network_policy_id

body

string

The ID of the QoS policy of the network where this port is plugged.

qos_policy_id

body

string

The ID of the QoS policy associated with the port.

revision_number

body

integer

The revision number of the resource.

resource_request (Optional)

body

object

Expose Placement resources (i.e.: minimum-bandwidth) and traits (i.e.: vnic-type, physnet) requested by a port to Nova and Placement. A resource_request object contains request_groups and same_subtree keys. request_groups is a list of dicts, where each dict represents one group of resources and traits that needs to be fulfilled from a single resource provider. Every dict in the list must contain id, required and resources keys. The id field is a string which represents a unique UUID that is generated for each group by combining the port_id and UUIDs of the QoS rules contributing to the group via the UUID5 method. required key contains the traits (generated from the vnic_type and the physnet) required by the port, and a resources key contains a mapping of requested resource class name and requested amount from the QoS policy. same_subtree key contains a list of id values from every resource group.

security_groups

body

array

The IDs of security groups applied to the port.

status

body

string

The port status. Values are ACTIVE, DOWN, BUILD and ERROR.

tags

body

array

The list of tags on the resource.

tenant_id

body

string

The ID of the project.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

propagate_uplink_status

body

boolean

The uplink status propagation of the port. Valid values are enabled (true) and disabled (false).

mac_learning_enabled (Optional)

body

boolean

A boolean value that indicates if MAC Learning is enabled on the associated port.

Response Example

{
    "port": {
        "admin_state_up": true,
        "allowed_address_pairs": [
            {
                "ip_address": "192.168.13.7",
                "mac_address": "fa:16:3e:09:1f:b2"
            }
        ],
        "binding:host_id": "",
        "binding:profile": {},
        "binding:vif_details": {},
        "binding:vif_type": "unbound",
        "binding:vnic_type": "normal",
        "created_at": "2023-04-20T02:32:41",
        "data_plane_status": null,
        "description": "",
        "device_id": "",
        "device_owner": "",
        "dns_assignment": [],
        "dns_domain": "",
        "dns_name": "",
        "extra_dhcp_opts": [],
        "fixed_ips": [
            {
                "ip_address": "192.168.13.6",
                "subnet_id": "a4c3b506-2110-4929-a70a-bda534bc0b07"
            }
        ],
        "id": "dc67ee67-7acd-464d-98fd-4abef6d8759d",
        "ip_allocation": "immediate",
        "mac_address": "fa:16:3e:09:1f:b2",
        "mac_learning_enabled": false,
        "name": "test-port",
        "network_id": "99b8e526-e943-4463-aa28-a22395bed154",
        "port_security_enabled": true,
        "project_id": "294b394e8f454cc8b26bbe342bc210d3",
        "revision_number": 1,
        "security_groups": [
            "751d740a-b52b-46d9-bca8-a21e75c8a727"
        ],
        "status": "DOWN",
        "tags": [],
        "tenant_id": "294b394e8f454cc8b26bbe342bc210d3",
        "updated_at": "2023-04-20T02:32:41",
        "qos_network_policy_id": null,
        "qos_policy_id": null,
        "resource_request": null,
        "propagate_uplink_status": false,
        "trusted": true
    }
}
PUT
/v2.0/ports/{port_id}/remove_allowed_address_pairs

Remove allowed_address_pairs from port

Atomically removes a set of allowed_address_pairs from the port’s already existing allowed_address_pairs.

Normal response codes: 200

Error response codes: 400, 401, 404, 412

Request

Name

In

Type

Description

port_id

path

string

The ID of the port.

port

body

object

A port object.

allowed_address_pairs (Optional)

body

array

A set of zero or more allowed address pair objects each where address pair object contains an ip_address and mac_address. While the ip_address is required, the mac_address will be taken from the port if not specified. The value of ip_address can be an IP Address or a CIDR (if supported by the underlying extension plugin). A server connected to the port can send a packet with source address which matches one of the specified allowed address pairs.

Request Example

{
   "port" : {
        "allowed_address_pairs": [
            {
                "ip_address": "192.168.13.7",
                "mac_address": "fa:16:3e:09:1f:b2"
            }
        ]
   }
}

Response Parameters

Name

In

Type

Description

port

body

object

A port object.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

allowed_address_pairs

body

array

A set of zero or more allowed address pair objects each where address pair object contains an ip_address and mac_address. While the ip_address is required, the mac_address will be taken from the port if not specified. The value of ip_address can be an IP Address or a CIDR (if supported by the underlying extension plugin). A server connected to the port can send a packet with source address which matches one of the specified allowed address pairs.

binding:host_id

body

string

The ID of the host where the port resides.

binding:profile

body

object

A dictionary that enables the application running on the specific host to pass and receive vif port information specific to the networking back-end. The networking API does not define a specific format of this field. If the update request is null this response field will be {}.

binding:vif_details

body

object

A dictionary which contains additional information on the port. Currently the following fields are defined: port_filter and ovs_hybrid_plug. port_filter is a boolean indicating the networking service provides port filtering features such as security group and/or anti MAC/IP spoofing. ovs_hybrid_plug is a boolean used to inform an API consumer like nova that the hybrid plugging strategy for OVS should be used.

binding:vif_type

body

string

The type of which mechanism is used for the port. An API consumer like nova can use this to determine an appropriate way to attach a device (for example an interface of a virtual server) to the port. Available values currently defined includes ovs, bridge, macvtap, hw_veb, hostdev_physical, vhostuser, distributed and other. There are also special values: unbound and binding_failed. unbound means the port is not bound to a networking back-end. binding_failed means an error that the port failed to be bound to a networking back-end.

binding:vnic_type

body

string

The type of vNIC which this port should be attached to. This is used to determine which mechanism driver(s) to be used to bind the port. The valid values are normal, macvtap, direct, baremetal, direct-physical, virtio-forwarder, smart-nic and remote-managed. What type of vNIC is actually available depends on deployments.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

data_plane_status

body

string

Status of the underlying data plane of a port.

description

body

string

A human-readable description for the resource.

device_id

body

string

The ID of the device that uses this port. For example, a server instance or a logical router.

device_owner

body

string

The entity type that uses this port. For example, compute:nova (server instance), network:dhcp (DHCP agent) or network:router_interface (router interface).

dns_assignment

body

object

Data assigned to a port by the Networking internal DNS including the hostname, ip_address and fqdn.

dns_domain

body

string

A valid DNS domain.

dns_name

body

string

A valid DNS name.

extra_dhcp_opts

body

array

A set of zero or more extra DHCP option pairs. An option pair consists of an option value and name.

fixed_ips

body

array

The IP addresses for the port. If the port has multiple IP addresses, this field has multiple entries. Each entry consists of IP address (ip_address) and the subnet ID from which the IP address is assigned (subnet_id).

hints

body

object

Admin-only. The following values control Open vSwitch’s Userspace Tx packet steering feature:

  • {"openvswitch": {"other_config": {"tx-steering": "hash|thread"}}}

id

body

string

The ID of the resource.

ip_allocation

body

string

Indicates when ports use either deferred, immediate or no IP allocation (none).

mac_address

body

string

The MAC address of the port. If the port uses the direct-physical vnic_type then the value of this field is overwritten with the MAC address provided in the active binding:profile if any.

name

body

string

Human-readable name of the resource.

network_id

body

string

The ID of the attached network.

numa_affinity_policy (Optional)

body

string

The port NUMA affinity policy requested during the virtual machine scheduling. Values: None, required, preferred or legacy.

port_security_enabled

body

boolean

The port security status. A valid value is enabled (true) or disabled (false). If port security is enabled for the port, security group rules and anti-spoofing rules are applied to the traffic on the port. If disabled, no such rules are applied.

project_id

body

string

The ID of the project.

qos_network_policy_id

body

string

The ID of the QoS policy of the network where this port is plugged.

qos_policy_id

body

string

The ID of the QoS policy associated with the port.

revision_number

body

integer

The revision number of the resource.

resource_request (Optional)

body

object

Expose Placement resources (i.e.: minimum-bandwidth) and traits (i.e.: vnic-type, physnet) requested by a port to Nova and Placement. A resource_request object contains request_groups and same_subtree keys. request_groups is a list of dicts, where each dict represents one group of resources and traits that needs to be fulfilled from a single resource provider. Every dict in the list must contain id, required and resources keys. The id field is a string which represents a unique UUID that is generated for each group by combining the port_id and UUIDs of the QoS rules contributing to the group via the UUID5 method. required key contains the traits (generated from the vnic_type and the physnet) required by the port, and a resources key contains a mapping of requested resource class name and requested amount from the QoS policy. same_subtree key contains a list of id values from every resource group.

security_groups

body

array

The IDs of security groups applied to the port.

status

body

string

The port status. Values are ACTIVE, DOWN, BUILD and ERROR.

tags

body

array

The list of tags on the resource.

tenant_id

body

string

The ID of the project.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

propagate_uplink_status

body

boolean

The uplink status propagation of the port. Valid values are enabled (true) and disabled (false).

mac_learning_enabled (Optional)

body

boolean

A boolean value that indicates if MAC Learning is enabled on the associated port.

Response Example

{
    "port": {
        "admin_state_up": true,
        "allowed_address_pairs": [],
        "binding:host_id": "",
        "binding:profile": {},
        "binding:vif_details": {},
        "binding:vif_type": "unbound",
        "binding:vnic_type": "normal",
        "created_at": "2023-04-20T02:32:41",
        "data_plane_status": null,
        "description": "",
        "device_id": "",
        "device_owner": "",
        "dns_assignment": [],
        "dns_domain": "",
        "dns_name": "",
        "extra_dhcp_opts": [],
        "fixed_ips": [
            {
                "ip_address": "192.168.13.6",
                "subnet_id": "a4c3b506-2110-4929-a70a-bda534bc0b07"
            }
        ],
        "id": "dc67ee67-7acd-464d-98fd-4abef6d8759d",
        "ip_allocation": "immediate",
        "mac_address": "fa:16:3e:09:1f:b2",
        "mac_learning_enabled": false,
        "name": "test-port",
        "network_id": "99b8e526-e943-4463-aa28-a22395bed154",
        "port_security_enabled": true,
        "project_id": "294b394e8f454cc8b26bbe342bc210d3",
        "revision_number": 1,
        "security_groups": [
            "751d740a-b52b-46d9-bca8-a21e75c8a727"
        ],
        "status": "DOWN",
        "tags": [],
        "tenant_id": "294b394e8f454cc8b26bbe342bc210d3",
        "updated_at": "2023-04-20T02:32:41",
        "qos_network_policy_id": null,
        "qos_policy_id": null,
        "resource_request": null,
        "propagate_uplink_status": false,
        "hardware_offload_type": "",
        "trusted": true
    }
}

Port Binding

Expose port bindings of a virtual port to external application.

Port Bindings Extended

The Port Bindings Extended extension adds extra fields to Port Binding like status and project id, and allows the activation of the binding.

GET
/v2.0/ports/{port_id}/bindings

Show Port Binding of a Port

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

port_id

path

string

The ID of the port.

Response Parameters

Name

In

Type

Description

bindings

body

object

A binding object.

host

body

string

The hostname of the system the agent is running on.

profile

body

object

A dictionary that enables the application running on the specific host to pass and receive vif port information specific to the networking back-end. The networking API does not define a specific format of this field. If the update request is null this response field will be {}.

vif_details

body

object

A dictionary which contains additional information on the port. Currently the following fields are defined: port_filter and ovs_hybrid_plug. port_filter is a boolean indicating the networking service provides port filtering features such as security group and/or anti MAC/IP spoofing. ovs_hybrid_plug is a boolean used to inform an API consumer like nova that the hybrid plugging strategy for OVS should be used.

vif_type

body

string

The type of which mechanism is used for the port. An API consumer like nova can use this to determine an appropriate way to attach a device (for example an interface of a virtual server) to the port. Available values currently defined includes ovs, bridge, macvtap, hw_veb, hostdev_physical, vhostuser, distributed and other. There are also special values: unbound and binding_failed. unbound means the port is not bound to a networking back-end. binding_failed means an error that the port failed to be bound to a networking back-end.

vnic_type

body

string

The type of vNIC which this port should be attached to. This is used to determine which mechanism driver(s) to be used to bind the port. The valid values are normal, macvtap, direct, baremetal, direct-physical, virtio-forwarder, smart-nic and remote-managed. What type of vNIC is actually available depends on deployments.

Response Example (Admin user)

{
    "bindings" : [
        {
            "host" : "jammy",
            "profile" : {},
            "status" : "ACTIVE",
            "vif_details" : {
                "bridge_name" : "br-int",
                "connectivity" : "l2",
                "datapath_type" : "system",
                "ovs_hybrid_plug" : false,
                "port_filter" : true
            },
            "vif_type" : "ovs",
            "vnic_type" : "normal"
        }
   ]
}
POST
/v2.0/ports/{port_id}/bindings/

Create Port binding

Normal response codes: 201

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

port_id

path

string

The ID of the port.

bindings

body

object

A binding object.

host

body

string

The hostname of the system the agent is running on.

profile

body

object

A dictionary that enables the application running on the specific host to pass and receive vif port information specific to the networking back-end. The networking API does not define a specific format of this field. If the update request is null this response field will be {}.

vif_details

body

object

A dictionary which contains additional information on the port. Currently the following fields are defined: port_filter and ovs_hybrid_plug. port_filter is a boolean indicating the networking service provides port filtering features such as security group and/or anti MAC/IP spoofing. ovs_hybrid_plug is a boolean used to inform an API consumer like nova that the hybrid plugging strategy for OVS should be used.

vif_type

body

string

The type of which mechanism is used for the port. An API consumer like nova can use this to determine an appropriate way to attach a device (for example an interface of a virtual server) to the port. Available values currently defined includes ovs, bridge, macvtap, hw_veb, hostdev_physical, vhostuser, distributed and other. There are also special values: unbound and binding_failed. unbound means the port is not bound to a networking back-end. binding_failed means an error that the port failed to be bound to a networking back-end.

vnic_type

body

string

The type of vNIC which this port should be attached to. This is used to determine which mechanism driver(s) to be used to bind the port. The valid values are normal, macvtap, direct, baremetal, direct-physical, virtio-forwarder, smart-nic and remote-managed. What type of vNIC is actually available depends on deployments.

Request Example (Admin user)

{
    "binding": {
        "host": "compute"
    }
}

Response Parameters

Name

In

Type

Description

port_id

path

string

The ID of the port.

bindings

body

object

A binding object.

host

body

string

The hostname of the system the agent is running on.

profile

body

object

A dictionary that enables the application running on the specific host to pass and receive vif port information specific to the networking back-end. The networking API does not define a specific format of this field. If the update request is null this response field will be {}.

vif_details

body

object

A dictionary which contains additional information on the port. Currently the following fields are defined: port_filter and ovs_hybrid_plug. port_filter is a boolean indicating the networking service provides port filtering features such as security group and/or anti MAC/IP spoofing. ovs_hybrid_plug is a boolean used to inform an API consumer like nova that the hybrid plugging strategy for OVS should be used.

vif_type

body

string

The type of which mechanism is used for the port. An API consumer like nova can use this to determine an appropriate way to attach a device (for example an interface of a virtual server) to the port. Available values currently defined includes ovs, bridge, macvtap, hw_veb, hostdev_physical, vhostuser, distributed and other. There are also special values: unbound and binding_failed. unbound means the port is not bound to a networking back-end. binding_failed means an error that the port failed to be bound to a networking back-end.

vnic_type

body

string

The type of vNIC which this port should be attached to. This is used to determine which mechanism driver(s) to be used to bind the port. The valid values are normal, macvtap, direct, baremetal, direct-physical, virtio-forwarder, smart-nic and remote-managed. What type of vNIC is actually available depends on deployments.

Response Example (admin user)

{
    "binding": {
        "host": "compute",
        "vif_type": "ovs",
        "vnic_type": "normal",
        "status": "INACTIVE",
        "profile": {},
        "vif_details": {
            "connectivity": "l2",
            "port_filter": true,
            "ovs_hybrid_plug": false,
            "datapath_type": "system",
            "bridge_name": "br-int"
        }
    }
}
PUT
/v2.0/ports/{port_id}/bindings/{host}/activate

Activate Port binding

Normal response codes: 200

Error response codes: 400, 401, 404, 412

Request

Name

In

Type

Description

port_id

path

string

The ID of the port.

host

body

string

The hostname of the system the agent is running on.

Response Parameters

Name

In

Type

Description

port_id

path

string

The ID of the port.

bindings

body

object

A binding object.

host

body

string

The hostname of the system the agent is running on.

profile

body

object

A dictionary that enables the application running on the specific host to pass and receive vif port information specific to the networking back-end. The networking API does not define a specific format of this field. If the update request is null this response field will be {}.

vif_details

body

object

A dictionary which contains additional information on the port. Currently the following fields are defined: port_filter and ovs_hybrid_plug. port_filter is a boolean indicating the networking service provides port filtering features such as security group and/or anti MAC/IP spoofing. ovs_hybrid_plug is a boolean used to inform an API consumer like nova that the hybrid plugging strategy for OVS should be used.

vif_type

body

string

The type of which mechanism is used for the port. An API consumer like nova can use this to determine an appropriate way to attach a device (for example an interface of a virtual server) to the port. Available values currently defined includes ovs, bridge, macvtap, hw_veb, hostdev_physical, vhostuser, distributed and other. There are also special values: unbound and binding_failed. unbound means the port is not bound to a networking back-end. binding_failed means an error that the port failed to be bound to a networking back-end.

vnic_type

body

string

The type of vNIC which this port should be attached to. This is used to determine which mechanism driver(s) to be used to bind the port. The valid values are normal, macvtap, direct, baremetal, direct-physical, virtio-forwarder, smart-nic and remote-managed. What type of vNIC is actually available depends on deployments.

Response Example (admin user)

{
    "binding": {
        "host": "compute",
        "vif_type": "ovs",
        "vnic_type": "normal",
        "status": "ACTIVE",
        "profile": {},
        "vif_details": {
            "connectivity": "l2",
            "port_filter": true,
            "ovs_hybrid_plug": false,
            "datapath_type": "system",
            "bridge_name": "br-int"
        }
    }
}
DELETE
/v2.0/ports/{port_id}/bindings/{host}

Delete Port Binding

Normal response codes: 204

Error response codes: 401, 403, 404, 412

Request

Name

In

Type

Description

port_id

path

string

The ID of the port.

host

body

string

The hostname of the system the agent is running on.

Response

There is no body content for the response of a successful DELETE request.

Segments

Lists, shows details for, creates, updates, and deletes segments. The segments API is admin-only.

Resource timestamps

The standard-attr-timestamp extension adds the created_at and updated_at attributes to all resources that have standard attributes.

GET
/v2.0/segments/{segment_id}

Show segment details

Shows details for a segment.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

segment_id

path

string

The UUID of the segment.

Response Parameters

Name

In

Type

Description

id

body

string

The UUID of the segment.

network_id

body

string

The ID of the attached network.

physical_network

body

string

The physical network where this network/segment is implemented.

network_type

body

string

The type of physical network that maps to this network resource. For example, flat, vlan, vxlan, or gre.

revision_number

body

integer

The revision number of the resource.

segmentation_id

body

integer

The ID of the isolated segment on the physical network. The network_type attribute defines the segmentation model. For example, if the network_type value is vlan, this ID is a vlan identifier. If the network_type value is gre, this ID is a gre key. Note that only the segmentation-id of VLAN type networks can be changed!

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

Response Example

{
  "segment": {
    "name": null,
    "network_id": "5c0cb560-4089-41dd-be29-469907a23b49",
    "segmentation_id": 2000,
    "network_type": "vlan",
    "physical_network": "segment-1",
    "revision_number": 1,
    "id": "57fe85e4-ca2f-4192-b3cd-d5c249d7a21f",
    "created_at": "2018-03-19T19:16:56Z",
    "updated_at": "2018-03-19T19:16:56Z",
    "description": null
  }
}
PUT
/v2.0/segments/{segment_id}

Update segment

Updates a segment.

Normal response codes: 200

Error response codes: 400, 401, 403, 404, 412

Request

Name

In

Type

Description

segment_id

path

string

The UUID of the segment.

name (Optional)

body

string

Human-readable name of the segment.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

Request Example

{
    "segment": {
        "name": "1",
        "description": "Segment One"
    }
}

Response Parameters

Name

In

Type

Description

id

body

string

The UUID of the segment.

network_id

body

string

The ID of the attached network.

physical_network

body

string

The physical network where this network/segment is implemented.

network_type

body

string

The type of physical network that maps to this network resource. For example, flat, vlan, vxlan, or gre.

revision_number

body

integer

The revision number of the resource.

segmentation_id

body

integer

The ID of the isolated segment on the physical network. The network_type attribute defines the segmentation model. For example, if the network_type value is vlan, this ID is a vlan identifier. If the network_type value is gre, this ID is a gre key. Note that only the segmentation-id of VLAN type networks can be changed!

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

Response Example

{
  "segment": {
    "name": "1",
    "network_id": "5c0cb560-4089-41dd-be29-469907a23b49",
    "segmentation_id": 2000,
    "network_type": "vlan",
    "physical_network": "segment-1",
    "revision_number": 4,
    "id": "57fe85e4-ca2f-4192-b3cd-d5c249d7a21f",
    "created_at": "2018-03-19T19:16:56Z",
    "updated_at": "2018-03-19T19:16:56Z",
    "description": "Segment One"
  }
}
DELETE
/v2.0/segments/{segment_id}

Delete segment

Deletes a segment and its associated resources.

Normal response codes: 204

Error response codes: 401, 404, 409, 412

Request

Name

In

Type

Description

segment_id

path

string

The UUID of the segment.

Response

There is no body content for the response of a successful DELETE request.

GET
/v2.0/segments

List segments

Lists segments to which the project has access.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

id (Optional)

query

string

Filter the list result by the ID of the resource.

network_id (Optional)

query

string

Filter the list result by the ID of the attached network.

physical_network (Optional)

query

string

Filter the list result by the physical network where this network/segment is implemented.

network_type (Optional)

query

string

Filter the list result by the type of physical network that this network/segment is mapped to. For example, flat, vlan, vxlan, or gre. Valid values depend on a networking back-end.

revision_number (Optional)

query

integer

Filter the list result by the revision number of the resource.

segmentation_id (Optional)

query

integer

Filter the list result by the ID of the isolated segment on the physical network.

name (Optional)

query

string

Filter the list result by the human-readable name of the resource.

description (Optional)

query

string

Filter the list result by the human-readable description of the resource.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a segment attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • id

  • name

  • network_id

  • network_type

  • physical_network

  • segmentation_id

  • tenant_id

  • project_id

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

id

body

string

The UUID of the segment.

network_id

body

string

The ID of the attached network.

physical_network

body

string

The physical network where this network/segment is implemented.

network_type

body

string

The type of physical network that maps to this network resource. For example, flat, vlan, vxlan, or gre.

revision_number

body

integer

The revision number of the resource.

segmentation_id

body

integer

The ID of the isolated segment on the physical network. The network_type attribute defines the segmentation model. For example, if the network_type value is vlan, this ID is a vlan identifier. If the network_type value is gre, this ID is a gre key. Note that only the segmentation-id of VLAN type networks can be changed!

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

Response Example

{
  "segments": [
    {
      "name": null,
      "network_id": "5c0cb560-4089-41dd-be29-469907a23b49",
      "segmentation_id": 2000,
      "network_type": "vlan",
      "physical_network": "segment-1",
      "revision_number": 1,
      "id": "57fe85e4-ca2f-4192-b3cd-d5c249d7a21f",
      "created_at": "2018-03-19T19:16:56Z",
      "updated_at": "2018-03-19T19:16:56Z",
      "description": null
    },
    {
      "name": null,
      "network_id": "5c0cb560-4089-41dd-be29-469907a23b49",
      "segmentation_id": 2000,
      "network_type": "vlan",
      "physical_network": "segment-2",
      "revision_number": 3,
      "id": "f1364c3a-4fc1-4206-b2dc-3254bc25cbfc",
      "created_at": "2018-03-19T19:16:56Z",
      "updated_at": "2018-03-19T19:16:56Z",
      "description": null
    }
  ]
}
POST
/v2.0/segments

Create segment

Creates a segment.

Normal response codes: 201

Error response codes: 400, 401

Request

Name

In

Type

Description

network_id

body

string

The ID of the attached network.

physical_network

body

string

The physical network where this network/segment is implemented.

network_type

body

string

The type of physical network that maps to this network resource. For example, flat, vlan, vxlan, or gre.

segmentation_id

body

integer

The ID of the isolated segment on the physical network. The network_type attribute defines the segmentation model. For example, if the network_type value is vlan, this ID is a vlan identifier. If the network_type value is gre, this ID is a gre key. Note that only the segmentation-id of VLAN type networks can be changed!

name (Optional)

body

string

Human-readable name of the segment.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

Request Example

{
    "segment": {
        "network_id": "5c0cb560-4089-41dd-be29-469907a23b49",
        "segmentation_id": 2000,
        "network_type": "vlan",
        "physical_network": "segment-1"
    }
}

Response Parameters

Name

In

Type

Description

id

body

string

The UUID of the segment.

network_id

body

string

The ID of the attached network.

physical_network

body

string

The physical network where this network/segment is implemented.

network_type

body

string

The type of physical network that maps to this network resource. For example, flat, vlan, vxlan, or gre.

revision_number

body

integer

The revision number of the resource.

segmentation_id

body

integer

The ID of the isolated segment on the physical network. The network_type attribute defines the segmentation model. For example, if the network_type value is vlan, this ID is a vlan identifier. If the network_type value is gre, this ID is a gre key. Note that only the segmentation-id of VLAN type networks can be changed!

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

Response Example

{
  "segment": {
    "name": null,
    "network_id": "5c0cb560-4089-41dd-be29-469907a23b49",
    "segmentation_id": 2000,
    "network_type": "vlan",
    "physical_network": "segment-1",
    "revision_number": 1,
    "id": "57fe85e4-ca2f-4192-b3cd-d5c249d7a21f",
    "created_at": "2018-03-19T19:16:56Z",
    "updated_at": "2018-03-19T19:16:56Z",
    "description": null
  }
}

Trunk networking

The trunk extension can be used to multiplex packets coming from and going to multiple neutron logical networks using a single neutron logical port. A trunk is modeled in neutron as a collection of neutron logical ports. One port, called parent port, must be associated to a trunk and it is the port to be used to connect instances with neutron. A sequence of subports (or sub_ports) each typically belonging to distinct neutron networks, is also associated to a trunk, and each subport may have a segmentation type and ID used to mux/demux the traffic coming in and out of the parent port.

In more details, the extension introduces the following resources:

  • trunk. A top level logical entity to model the group of neutron logical networks whose traffic flows through the trunk.

  • sub_port. An association to a neutron logical port with attributes segmentation_id and segmentation_type.

Resource timestamps

The standard-attr-timestamp extension adds the created_at and updated_at attributes to all resources that have standard attributes.

Tag extension

The standard-attr-tag adds Tag support for resources with standard attributes by adding the tags attribute allowing consumers to associate tags with resources.

GET
/v2.0/trunks

List trunks

Lists trunks that are accessible to the user who submits the request.

Default policy settings return only those trunks that are owned by the user who submits the request, unless an admin user submits the request.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401, 404

Request Parameters

Name

In

Type

Description

admin_state_up (Optional)

query

boolean

Filter the trunk list result by the administrative state of the trunk, which is up (true) or down (false).

description (Optional)

query

string

Filter the list result by the human-readable description of the resource.

id (Optional)

query

string

Filter the list result by the ID of the resource.

name (Optional)

query

string

Filter the list result by the human-readable name of the resource.

port_id (Optional)

query

string

Filter the trunk list result by the ID of the parent port.

revision_number (Optional)

query

integer

Filter the list result by the revision number of the resource.

status (Optional)

query

string

Filter the trunk list result by the status for the trunk. Possible values are ACTIVE, DOWN, BUILD, DEGRADED, and ERROR.

tenant_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

project_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a trunk attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • admin_state_up

  • id

  • name

  • port_id

  • project_id

  • status

  • tenant_id

tags (Optional)

query

string

A list of tags to filter the list result by. Resources that match all tags in this list will be returned. Tags in query must be separated by comma.

tags-any (Optional)

query

string

A list of tags to filter the list result by. Resources that match any tag in this list will be returned. Tags in query must be separated by comma.

not-tags (Optional)

query

string

A list of tags to filter the list result by. Resources that match all tags in this list will be excluded. Tags in query must be separated by comma.

not-tags-any (Optional)

query

string

A list of tags to filter the list result by. Resources that match any tag in this list will be excluded. Tags in query must be separated by comma.

Response Parameters

Name

In

Type

Description

admin_state_up (Optional)

body

boolean

The administrative state of the trunk, which is up (true) or down (false).

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

description

body

string

The description for the resource.

id

body

string

The ID for the resource.

name (Optional)

body

string

The name of the resource.

port_id

body

string

The ID of the parent port.

revision_number

body

integer

The revision number of the resource.

status

body

string

The status for the trunk. Possible values are ACTIVE, DOWN, BUILD, DEGRADED, and ERROR.

tenant_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

project_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

sub_ports

body

array

A list of ports associated with the trunk.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

tags

body

array

The list of tags on the resource.

Response Example

{
    "trunks": [
        {
            "status": "DOWN",
            "sub_ports": [],
            "name": "test",
            "admin_state_up": true,
            "project_id": "313be01bd0744cea86643c711c57012b",
            "tenant_id": "313be01bd0744cea86643c711c57012b",
            "created_at": "2016-10-05T20:11:16Z",
            "updated_at": "2016-10-05T20:11:16Z",
            "revision_number": 1,
            "port_id": "8027c4da-772f-4e43-bfbf-023b4a4e63de",
            "id": "ee98bdb4-a817-43af-943f-4318bff98f51",
            "description": ""
        }
    ]
}
POST
/v2.0/trunks

Create trunk

Error codes:

  • 400 The operation returns this error code if the request is malformed, e.g. there are missing or invalid parameters in the request.

  • 401 The operation is not authorized.

  • 404 If the extension is not available or the port UUID of any of the specified ports is not found.

  • 409 The operation returns this error code for one of these reasons:

    • A port to be used as subport is in use by another trunk.

    • The segmentation type and segmentation ID are already in use in the trunk.

    • A port to be used as parent port is in use by another trunk or cannot be trunked.

    • A system configuration prevents the operation from succeeding.

Normal response codes: 201

Error response codes: 400, 401, 404, 409

Request

Name

In

Type

Description

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

port_id

body

string

The ID of the parent port.

name (Optional)

body

string

The name of the resource.

description

body

string

The description for the resource.

admin_state_up (Optional)

body

boolean

The administrative state of the trunk, which is up (true) or down (false).

sub_ports

body

array

A list of ports associated with the trunk.

Request Example

{
    "trunk": {
        "port_id": "8027c4da-772f-4e43-bfbf-023b4a4e63de",
        "name": "test",
        "admin_state_up": true
    }
}

Response Parameters

Name

In

Type

Description

admin_state_up (Optional)

body

boolean

The administrative state of the trunk, which is up (true) or down (false).

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

description

body

string

The description for the resource.

id

body

string

The ID for the resource.

name (Optional)

body

string

The name of the resource.

port_id

body

string

The ID of the parent port.

revision_number

body

integer

The revision number of the resource.

status

body

string

The status for the trunk. Possible values are ACTIVE, DOWN, BUILD, DEGRADED, and ERROR.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

sub_ports

body

array

A list of ports associated with the trunk.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

tags

body

array

The list of tags on the resource.

Response Example

{
    "trunk": {
        "status": "DOWN",
        "sub_ports": [],
        "name": "test",
        "admin_state_up": true,
        "project_id": "145a14e4a64b49bf98baad8945dbd4f1",
        "tenant_id": "145a14e4a64b49bf98baad8945dbd4f1",
        "created_at": "2016-10-05T22:31:37Z",
        "updated_at": "2016-10-05T22:31:37Z",
        "revision_number": 1,
        "port_id": "8027c4da-772f-4e43-bfbf-023b4a4e63de",
        "id": "114a26b1-d124-4835-bb4f-021d3d886023",
        "description": ""
    }
}
PUT
/v2.0/trunks/{trunk_id}/add_subports

Add subports to trunk

Normal response codes: 200

Error response codes: 400, 401, 404, 409

Request

Name

In

Type

Description

trunk_id

path

string

The ID of the trunk.

segmentation_id (Optional)

body

integer

The segmentation ID for the subport.

segmentation_type (Optional)

body

string

The segmentation type for the subport. Possible values include vlan and inherit. When inherit is specified, a port gets its segmentation type from the network its connected to.

port_id

body

string

The ID of the subport.

Request Example

{
    "sub_ports": [
        {
            "segmentation_id": 44,
            "port_id": "4b4c691b-086d-43d2-8a65-5487e9434155",
            "segmentation_type": "vlan"
        }
    ]
}

Response Parameters

Name

In

Type

Description

admin_state_up (Optional)

body

boolean

The administrative state of the trunk, which is up (true) or down (false).

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

description

body

string

The description for the resource.

id

body

string

The ID for the resource.

name (Optional)

body

string

The name of the resource.

port_id

body

string

The ID of the parent port.

revision_number

body

integer

The revision number of the resource.

status

body

string

The status for the trunk. Possible values are ACTIVE, DOWN, BUILD, DEGRADED, and ERROR.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

sub_ports

body

array

A list of ports associated with the trunk.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

tags

body

array

The list of tags on the resource.

Response Example

{
    "status": "DOWN",
    "sub_ports": [
        {
            "segmentation_type": "vlan",
            "port_id": "4b4c691b-086d-43d2-8a65-5487e9434155",
            "segmentation_id": 44
        }
    ],
    "name": "test",
    "admin_state_up": true,
    "project_id": "145a14e4a64b49bf98baad8945dbd4f1",
    "tenant_id": "145a14e4a64b49bf98baad8945dbd4f1",
    "created_at": "2016-10-05T22:31:37Z",
    "updated_at": "2016-10-05T22:52:04Z",
    "revision_number": 2,
    "port_id": "8027c4da-772f-4e43-bfbf-023b4a4e63de",
    "id": "114a26b1-d124-4835-bb4f-021d3d886023",
    "description": ""
}
PUT
/v2.0/trunks/{trunk_id}/remove_subports

Delete subports from trunk

Normal response codes: 200

Error response codes: 400, 401, 404, 409

Request

Name

In

Type

Description

trunk_id

path

string

The ID of the trunk.

port_id

body

string

The ID of the port.

Request Example

{
    "sub_ports": [
       {
           "port_id": "4b4c691b-086d-43d2-8a65-5487e9434155"
       }
    ]
}

Response Parameters

Name

In

Type

Description

admin_state_up (Optional)

body

boolean

The administrative state of the trunk, which is up (true) or down (false).

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

description

body

string

The description for the resource.

id

body

string

The ID for the resource.

name (Optional)

body

string

The name of the resource.

port_id

body

string

The ID of the parent port.

revision_number

body

integer

The revision number of the resource.

status

body

string

The status for the trunk. Possible values are ACTIVE, DOWN, BUILD, DEGRADED, and ERROR.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

sub_ports

body

array

A list of ports associated with the trunk.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

tags

body

array

The list of tags on the resource.

Response Example

{
    "status": "DOWN",
    "sub_ports": [],
    "name": "test",
    "admin_state_up": true,
    "project_id": "145a14e4a64b49bf98baad8945dbd4f1",
    "tenant_id": "145a14e4a64b49bf98baad8945dbd4f1",
    "created_at": "2016-10-05T22:31:37Z",
    "updated_at": "2016-10-05T22:57:44Z",
    "revision_number": 3,
    "port_id": "8027c4da-772f-4e43-bfbf-023b4a4e63de",
    "id": "114a26b1-d124-4835-bb4f-021d3d886023",
    "description": ""
}
GET
/v2.0/trunks/{trunk_id}/get_subports

List subports for trunk

Normal response codes: 200

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Error response codes: 401, 404

Request

Name

In

Type

Description

trunk_id

path

string

The ID of the trunk.

Response Parameters

Name

In

Type

Description

port_id

body

string

The ID of the subport.

segmentation_type

body

string

The segmentation type for the subport. Possible values include vlan and inherit. When inherit is specified, a port gets its segmentation type from the network its connected to.

segmentation_id (Optional)

body

integer

The segmentation ID for the subport.

tags

body

array

The list of tags on the resource.

Response Example

{
    "sub_ports": [
        {
            "segmentation_type": "vlan",
            "port_id": "4b4c691b-086d-43d2-8a65-5487e9434155",
            "segmentation_id": 44
        }
    ]
}
PUT
/v2.0/trunks/{trunk_id}

Update trunk

The update request is only for changing fields like name, description or admin_state_up. Setting the admin_state_up to False locks the trunk in that it prevents operations such as as adding/removing subports.

Normal response codes: 200

Error response codes: 400, 401, 404, 409, 412

Request

Name

In

Type

Description

name_resource (Optional)

body

string

The name of the resource.

admin_state_up_trunk

body

boolean

The administrative state of the resource, which is up (true) or down (false).

description_resource

body

string

The description for the resource.

trunk_id

path

string

The ID of the trunk.

Request Example

{
    "trunk": {
        "name": "foo",
        "admin_state_up": true
    }
}

Response Parameters

Name

In

Type

Description

admin_state_up (Optional)

body

boolean

The administrative state of the trunk, which is up (true) or down (false).

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

description

body

string

The description for the resource.

id

body

string

The ID for the resource.

name (Optional)

body

string

The name of the resource.

port_id

body

string

The ID of the parent port.

revision_number

body

integer

The revision number of the resource.

status

body

string

The status for the trunk. Possible values are ACTIVE, DOWN, BUILD, DEGRADED, and ERROR.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

sub_ports

body

array

A list of ports associated with the trunk.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

tags

body

array

The list of tags on the resource.

Response Example

{
    "trunk": {
        "status": "DOWN",
        "sub_ports": [
            {
                "segmentation_type": "vlan",
                "port_id": "4b4c691b-086d-43d2-8a65-5487e9434155",
                "segmentation_id": 44
            }
        ],
        "name": "foo",
        "admin_state_up": true,
        "project_id": "145a14e4a64b49bf98baad8945dbd4f1",
        "tenant_id": "145a14e4a64b49bf98baad8945dbd4f1",
        "created_at": "2016-10-05T22:31:37Z",
        "updated_at": "2016-10-05T23:28:17Z",
        "revision_number": 9,
        "port_id": "8027c4da-772f-4e43-bfbf-023b4a4e63de",
        "id": "114a26b1-d124-4835-bb4f-021d3d886023",
        "description": ""
    }
}
GET
/v2.0/trunks/{trunk_id}

Show trunk

Shows details for a trunk.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

trunk_id

path

string

The ID of the trunk.

Response Parameters

Name

In

Type

Description

admin_state_up (Optional)

body

boolean

The administrative state of the trunk, which is up (true) or down (false).

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

description

body

string

The description for the resource.

id

body

string

The ID for the resource.

name (Optional)

body

string

The name of the resource.

port_id

body

string

The ID of the parent port.

revision_number

body

integer

The revision number of the resource.

status

body

string

The status for the trunk. Possible values are ACTIVE, DOWN, BUILD, DEGRADED, and ERROR.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

sub_ports

body

array

A list of ports associated with the trunk.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

tags

body

array

The list of tags on the resource.

Response Example

{
    "trunk": {
        "status": "DOWN",
        "sub_ports": [
            {
                 "segmentation_type": "vlan",
                 "port_id": "4b4c691b-086d-43d2-8a65-5487e9434155",
                 "segmentation_id": 44
            }
        ],
        "name": "foo",
        "admin_state_up": true,
        "project_id": "145a14e4a64b49bf98baad8945dbd4f1",
        "tenant_id": "145a14e4a64b49bf98baad8945dbd4f1",
        "created_at": "2016-10-05T22:31:37Z",
        "updated_at": "2016-10-05T23:28:17Z",
        "revision_number": 9,
        "port_id": "8027c4da-772f-4e43-bfbf-023b4a4e63de",
        "id": "114a26b1-d124-4835-bb4f-021d3d886023",
        "description": ""
    }
}
DELETE
/v2.0/trunks/{trunk_id}

Delete trunk

Deletes a trunk, if its state allows it.

Normal response codes: 204

Error response codes: 401, 404, 409, 412

Request

Name

In

Type

Description

trunk_id

path

string

The ID of the trunk.

Trunk details extended attributes (ports)

The trunk_details extension attribute is available when showing a port resource that participates in a trunk as parent. The extension is useful for REST clients that may want to access trunk details when getting the parent port, and it allows them to avoid extra lookups.

GET
/v2.0/ports/{port_id}

Show trunk details

Shows details for a port. The details available in the trunk_details attribute contain the trunk ID and the array showing information about the subports that belong to the trunk: the port UUID, the segmentation type, the segmentation ID, and the MAC address.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Request

Name

In

Type

Description

port_id

path

string

The ID of the port.

Response Parameters

Name

In

Type

Description

trunk_details (Optional)

body

dict

The details about the trunk.

Response Example

{
    "port": {
        "status": "DOWN",
        "created_at": "2016-10-05T20:05:14Z",
        "description": "",
        "admin_state_up": true,
        "network_id": "1cf9e069-365f-4a78-8784-616bc12c4c5a",
        "project_id": "313be01bd0744cea86643c711c57012b",
        "tenant_id": "313be01bd0744cea86643c711c57012b",
        "extra_dhcp_opts": [],
        "updated_at": "2016-10-05T20:05:14Z",
        "name": "test",
        "device_owner": "",
        "trunk_details": {
            "trunk_id": "8905d084-010c-46e8-a863-f21cb4441ab1",
            "sub_ports": [
               {
                   "segmentation_id": 33,
                   "port_id": "70df9f3e-b409-4761-8304-ce029b2079f5",
                   "segmentation_type": "vlan",
                   "mac_address": "fa:16:3e:86:9b:dc"
               },
               {
                   "segmentation_id": 44,
                   "port_id": "4b4c691b-086d-43d2-8a65-5487e9434155",
                   "segmentation_type": "vlan",
                   "mac_address": "fa:16:3e:fe:29:97"
               }
           ]
       },
       "revision_number": 5,
       "mac_address": "fa:16:3e:5c:e9:a3",
       "fixed_ips": [
           {
               "subnet_id": "76a059c0-b189-479f-882c-5e8bd464ea49",
               "ip_address": "40.0.0.3"
           }
       ],
       "id": "8027c4da-772f-4e43-bfbf-023b4a4e63de",
       "security_groups": ["da88a249-12ac-4221-9565-c406b6feeb48"],
       "device_id": ""
    }
}

Layer 3 Networking

Address scopes

Lists, creates, shows details for, updates, and deletes address scopes.

GET
/v2.0/address-scopes/{address_scope_id}

Show address scope

Shows information for an address scope.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

address_scope_id

path

string

The ID of the address scope.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

address_scope

body

object

An address scope object.

id

body

string

The ID of the address scope.

name

body

string

Human-readable name of the resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

ip_version

body

integer

The IP protocol version. Valid value is 4 or 6. Default is 4.

shared

body

boolean

Indicates whether this resource is shared across all projects.

Response Example

{
    "address_scope": {
        "name": "address-scope-ip4",
        "tenant_id": "a7a7fa10fd7a4c80acb7e4b224480495",
        "ip_version": 4,
        "shared": true,
        "project_id": "a7a7fa10fd7a4c80acb7e4b224480495",
        "id": "4143da3e-d2a7-4077-ba80-215ecfd016d7"
    }
}
PUT
/v2.0/address-scopes/{address_scope_id}

Update an address scope

Updates an address scope.

Normal response codes: 200

Error response codes: 400, 401, 403, 404, 412

Request

Name

In

Type

Description

address_scope_id

path

string

The ID of the address scope.

address_scope

body

object

An address scope object.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

shared (Optional)

body

boolean

Indicates whether this resource is shared across all projects. By default, only administrative users can change this value.

Request Example

{
    "address_scope": {
        "name": "address-scope-ip4",
        "shared": true
    }
}

Response Parameters

Name

In

Type

Description

address_scope

body

object

An address scope object.

id

body

string

The ID of the address scope.

name

body

string

Human-readable name of the resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

ip_version

body

integer

The IP protocol version. Valid value is 4 or 6. Default is 4.

shared

body

boolean

Indicates whether this resource is shared across all projects.

Response Example

{
    "address_scope": {
        "name": "address-scope-2",
        "tenant_id": "a7a7fa10fd7a4c80acb7e4b224480495",
        "ip_version": 4,
        "shared": true,
        "project_id": "a7a7fa10fd7a4c80acb7e4b224480495",
        "id": "4143da3e-d2a7-4077-ba80-215ecfd016d7"
    }
}
DELETE
/v2.0/address-scopes/{address_scope_id}

Delete an address scope

Deletes an address scope.

Normal response codes: 204

Error response codes: 401, 404, 412

Request

Name

In

Type

Description

address_scope_id

path

string

The ID of the address scope.

Response

There is no body content for the response of a successful DELETE request.

GET
/v2.0/address-scopes

List address scopes

Lists address scopes that the project has access to.

Default policy settings return only the address scopes owned by the project of the user submitting the request, unless the user has administrative role.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

id (Optional)

query

string

Filter the list result by the ID of the resource.

name (Optional)

query

string

Filter the list result by the human-readable name of the resource.

tenant_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

project_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

ip_version (Optional)

query

integer

Filter the list result by the IP protocol version. Valid value is 4 or 6.

shared (Optional)

query

boolean

Admin-only. Filter the list result based on whether the resource is shared across all projects.

sort_key (Optional)

query

string

Sorts by an address scope attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • id

  • ip_version

  • name

  • project_id

  • shared

  • tenant_id

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

address_scopes

body

array

A list of address scope objects.

id

body

string

The ID of the address scope.

name

body

string

Human-readable name of the resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

ip_version

body

integer

The IP protocol version. Valid value is 4 or 6. Default is 4.

shared

body

boolean

Indicates whether this resource is shared across all projects.

Response Example

{
    "address_scopes": [
        {
            "name": "address-scope-ip6",
            "tenant_id": "a7a7fa10fd7a4c80acb7e4b224480495",
            "ip_version": 6,
            "shared": true,
            "project_id": "a7a7fa10fd7a4c80acb7e4b224480495",
            "id": "3b189848-58bb-4499-abc2-8df170a6a8ae"
        },
        {
            "name": "address-scope-2",
            "tenant_id": "a7a7fa10fd7a4c80acb7e4b224480495",
            "ip_version": 4,
            "shared": true,
            "project_id": "a7a7fa10fd7a4c80acb7e4b224480495",
            "id": "4143da3e-d2a7-4077-ba80-215ecfd016d7"
        }
    ]
}
POST
/v2.0/address-scopes

Create address scope

Creates an address scope.

Normal response codes: 201

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

address_scope

body

object

An address scope object.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

tenant_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

project_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

ip_version

body

integer

The IP protocol version. Valid value is 4 or 6.

shared (Optional)

body

boolean

Indicates whether this resource is shared across all projects. By default, only administrative users can change this value.

Request Example

{
    "address_scope": {
        "name": "address-scope-2",
        "tenant_id": "a7a7fa10fd7a4c80acb7e4b224480495",
        "ip_version": 4,
        "shared": true,
        "project_id": "a7a7fa10fd7a4c80acb7e4b224480495"
    }
}

Response Parameters

Name

In

Type

Description

address_scope

body

object

An address scope object.

id

body

string

The ID of the address scope.

name

body

string

Human-readable name of the resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

ip_version

body

integer

The IP protocol version. Valid value is 4 or 6. Default is 4.

shared

body

boolean

Indicates whether this resource is shared across all projects.

Response Example

{
    "address_scope": {
        "name": "address-scope-2",
        "tenant_id": "a7a7fa10fd7a4c80acb7e4b224480495",
        "ip_version": 4,
        "shared": true,
        "project_id": "a7a7fa10fd7a4c80acb7e4b224480495",
        "id": "4143da3e-d2a7-4077-ba80-215ecfd016d7"
    }
}

Routers Conntrack Helper (CT) target rules

Lists, creates, shows details for, updates, and deletes router conntrack helper (CT) target rules.

GET
/v2.0/routers/{router_id}/conntrack_helpers/{conntrack_helper_id}

Show conntrack helper

Shows information for a router conntrack helper.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 400, 404

Request

Name

In

Type

Description

router_id

path

string

The ID of the router.

conntrack_helper_id

path

string

The ID of the conntrack helper.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

conntrack_helper

body

object

A router conntrack helper object.

helper

body

string

The netfilter conntrack helper module.

id

body

string

The ID of the conntrack helper.

protocol

body

string

The network protocol for the netfilter conntrack target rule.

port

body

integer

The network port for the netfilter conntrack target rule.

Response Example

{
    "conntrack_helper": {
        "protocol": "tcp",
        "id": "2fc1eebb-e0fa-4c40-868a-7ace444717e1",
        "helper": "ftp",
        "port": 21
    }
}
PUT
/v2.0/routers/{router_id}/conntrack_helpers/{conntrack_helper_id}

Update a conntrack helper

Updates a router conntrack helper.

Normal response codes: 200

Error response codes: 400, 404

Request

Name

In

Type

Description

router_id

path

string

The ID of the router.

conntrack_helper_id

path

string

The ID of the conntrack helper.

helper (Optional)

body

string

The netfilter conntrack helper module.

protocol (Optional)

body

string

The network protocol for the netfilter conntrack target rule.

port (Optional)

body

integer

The network port for the netfilter conntrack target rule.

Request Example

{
    "conntrack_helper": {
        "helper": "tftp",
        "protocol": "udp",
        "port": 69
    }
}

Response Parameters

Name

In

Type

Description

conntrack_helper

body

object

A router conntrack helper object.

id

body

string

The ID of the conntrack helper.

helper

body

string

The netfilter conntrack helper module.

protocol

body

string

The network protocol for the netfilter conntrack target rule.

port

body

integer

The network port for the netfilter conntrack target rule.

Response Example

{
    "conntrack_helper": {
        "protocol": "udp",
        "id": "2fc1eebb-e0fa-4c40-868a-7ace444717e1",
        "helper": "tftp",
        "port": 69
    }
}
DELETE
/v2.0/routers/{router_id}/conntrack_helpers/{conntrack_helper_id}

Delete a conntrack helper

Deletes a router conntrack helper.

Normal response codes: 204

Error response codes: 404

Request

Name

In

Type

Description

router_id

path

string

The ID of the router.

conntrack_helper_id

path

string

The ID of the conntrack helper.

Response

There is no body content for the response of a successful DELETE request.

GET
/v2.0/routers/{router_id}/conntrack_helpers

List router conntrack helpers

Lists router conntrack helpers associated with a router.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 400, 404

Request

Name

In

Type

Description

router_id

path

string

The ID of the router.

id (Optional)

query

string

Filter the list result by the ID of the resource.

helper (Optional)

query

string

Filter the list result by the used helper.

protocol (Optional)

query

string

Filter the list result by the used protocol.

port (Optional)

query

integer

Filter the list result by the used port.

sort_key (Optional)

query

string

Sorts by a conntrack helper ID attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • id

  • helper

  • port

  • protocol

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

conntrack_helpers

body

array

A list of router conntrack helpers objects.

id

body

string

The ID of the conntrack helper.

helper

body

string

The netfilter conntrack helper module.

protocol

body

string

The network protocol for the netfilter conntrack target rule.

port

body

integer

The network port for the netfilter conntrack target rule.

Response Example

{
    "conntrack_helpers": [
        {
            "protocol": "udp",
            "id": "2fc1eebb-e0fa-4c40-868a-7ace444717e1",
            "helper": "tftp",
            "port": 6969
        },
        {
            "protocol": "tcp",
            "id": "ee7c890f-44fa-443d-9326-8574c1c3e5e1",
            "helper": "ftp",
            "port": 21
        }
    ]
}
POST
/v2.0/routers/{router_id}/conntrack_helpers

Create conntrack helper

Creates a router conntrack helper.

Normal response codes: 201

Error response codes: 400, 404

Request

Name

In

Type

Description

conntrack_helper

body

object

A router conntrack helper object.

router_id

path

string

The ID of the router.

helper

body

string

The netfilter conntrack helper module.

protocol

body

string

The network protocol for the netfilter conntrack target rule.

port

body

integer

The network port for the netfilter conntrack target rule.

Request Example

{
    "conntrack_helper": {
        "protocol": "udp",
        "port": 2121,
        "helper": "ftp"
    }
}

Response Parameters

Name

In

Type

Description

conntrack_helper

body

object

A router conntrack helper object.

id

body

string

The ID of the conntrack helper.

helper

body

string

The netfilter conntrack helper module.

protocol

body

string

The network protocol for the netfilter conntrack target rule.

port

body

integer

The network port for the netfilter conntrack target rule.

Response Example

{
    "conntrack_helper": {
        "protocol": "tcp",
        "id": "32925de7-580e-4ca9-bfd7-c2c2cefbd2ad",
        "helper": "ftp",
        "port": 21
    }
}

Floating IPs (floatingips)

DNS integration

The dns-integration extension adds the dns_name and dns_domain attributes to floating IPs allowing them to be specified at creation time. The data in these attributes will be published in an external DNS service when Neutron is configured to integrate with such a service.

Floating IP distributed

The floating-ip-distributed extension adds the distributed attribute to the floating IPs. The value of this attribute identify the Floating IP is distributed or centralized.

Floating IP port details

The fip-port-details extension adds the port_details attribute to floating IPs. The value of this attribute contains information of the associated port.

Floating IP port forwardings

The expose-port-forwarding-in-fip extension adds the port_forwardings attribute to floating IPs. The value of this attribute contains the information of associated port forwarding resources.

Floating IP port forwardings detail

The floating-ip-port-forwarding-detail extension adds the id and internal_port_id attribute to port_forwardings.

QoS extension

The QoS extension (qos) makes it possible to define QoS policies and associate these to the ports by introducing the qos_policy_id attribute. The policies should be created before they are associated to the floating IPs.

QoS network policy

The qos-fip extension adds the read only parameter qos_network_policy_id to the floating IP responses. This parameter contains the QoS policy ID of the network where this floating IP is allocated.

Resource timestamps

The standard-attr-timestamp extension adds the created_at and updated_at attributes to all resources that have standard attributes.

Tag extension

The standard-attr-tag adds Tag support for resources with standard attributes by adding the tags attribute allowing consumers to associate tags with resources.

GET
/v2.0/floatingips

List floating IPs

Lists floating IPs visible to the user.

Default policy settings return only the floating IPs owned by the user’s project, unless the user has admin role.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

This example request lists floating IPs in JSON format:

GET /v2.0/floatingips
Accept: application/json

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

id (Optional)

query

string

Filter the list result by the ID of the resource.

router_id (Optional)

query

string

Filter the floating IP list result by the ID of the router for the floating IP.

status (Optional)

query

string

Filter the floating IP list result by the status of the floating IP. Values are ACTIVE, DOWN and ERROR.

tenant_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

project_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

revision_number (Optional)

query

integer

Filter the list result by the revision number of the resource.

description (Optional)

query

string

Filter the list result by the human-readable description of the resource.

distributed (Optional)

body

boolean

true indicates a distributed floatingip. It is available when floating-ip-distributed extension is enabled.

floating_network_id (Optional)

query

string

Filter the floating IP list result by the ID of the network associated with the floating IP.

fixed_ip_address (Optional)

query

string

Filter the floating IP list result by the fixed IP address that is associated with the floating IP address.

floating_ip_address (Optional)

query

string

Filter the floating IP list result by the floating IP address.

port_id (Optional)

query

string

Filter the floating IP list result by the ID of a port associated with the floating IP.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a floatingip attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • fixed_ip_address

  • floating_ip_address

  • floating_network_id

  • id

  • router_id

  • status

  • tenant_id

  • project_id

tags (Optional)

query

string

A list of tags to filter the list result by. Resources that match all tags in this list will be returned. Tags in query must be separated by comma.

tags-any (Optional)

query

string

A list of tags to filter the list result by. Resources that match any tag in this list will be returned. Tags in query must be separated by comma.

not-tags (Optional)

query

string

A list of tags to filter the list result by. Resources that match all tags in this list will be excluded. Tags in query must be separated by comma.

not-tags-any (Optional)

query

string

A list of tags to filter the list result by. Resources that match any tag in this list will be excluded. Tags in query must be separated by comma.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

floatingips

body

array

A list of floatingip objects.

id

body

string

The ID of the floating IP address.

router_id

body

string

The ID of the router for the floating IP.

status

body

string

The status of the floating IP. Values are ACTIVE, DOWN and ERROR.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

revision_number

body

integer

The revision number of the resource.

description

body

string

A human-readable description for the resource.

distributed

body

boolean

true indicates a distributed floatingip. It is available when floating-ip-distributed extension is enabled.

dns_domain

body

string

A valid DNS domain.

dns_name

body

string

A valid DNS name.

port_details

body

string

The information of the port that this floating IP associates with. In particular, if the floating IP is associated with a port, this field contains some attributes of the associated port, including name, network_id, mac_address, admin_state_up, status, device_id and device_owner. If the floating IP is not associated with a port, this field is null.

qos_network_policy_id

body

string

The ID of the QoS policy of the network where this floating IP is plugged.

qos_policy_id

body

string

The ID of the QoS policy associated with the floating IP.

floating_network_id

body

string

The ID of the network associated with the floating IP.

fixed_ip_address

body

string

The fixed IP address that is associated with the floating IP address.

floating_ip_address

body

string

The floating IP address.

port_id

body

string

The ID of a port associated with the floating IP.

tags

body

array

The list of tags on the resource.

port_forwardings

body

array

The associated port forwarding resources for the floating IP. If the floating IP has multiple port forwarding resources, this field has multiple entries. Each entry consists of network IP protocol (protocol), the fixed IP address of internal neutron port (internal_ip_address), the TCP or UDP port or port range used by internal neutron port (internal_port) or (internal_port_range) and the TCP or UDP port or port range used by floating IP (external_port) or (external_port_range).

Response Example

{
    "floatingips": [
        {
            "router_id": "d23abc8d-2991-4a55-ba98-2aaea84cc72f",
            "description": "for test",
            "dns_domain": "my-domain.org.",
            "dns_name": "myfip",
            "created_at": "2016-12-21T10:55:50Z",
            "updated_at": "2016-12-21T10:55:53Z",
            "revision_number": 1,
            "project_id": "4969c491a3c74ee4af974e6d800c62de",
            "tenant_id": "4969c491a3c74ee4af974e6d800c62de",
            "floating_network_id": "376da547-b977-4cfe-9cba-275c80debf57",
            "fixed_ip_address": "10.0.0.3",
            "floating_ip_address": "172.24.4.228",
            "port_id": "ce705c24-c1ef-408a-bda3-7bbd946164ab",
            "id": "2f245a7b-796b-4f26-9cf9-9e82d248fda7",
            "status": "ACTIVE",
            "port_details": {
                "status": "ACTIVE",
                "name": "",
                "admin_state_up": true,
                "network_id": "02dd8479-ef26-4398-a102-d19d0a7b3a1f",
                "device_owner": "compute:nova",
                "mac_address": "fa:16:3e:b1:3b:30",
                "device_id": "8e3941b4-a6e9-499f-a1ac-2a4662025cba"
            },
            "tags": ["tag1,tag2"],
            "port_forwardings": [],
            "qos_network_policy_id": "174dd0c1-a4eb-49d4-a807-ae80246d82f4",
            "qos_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae"

        },
        {
            "router_id": null,
            "description": "for test",
            "dns_domain": "my-domain.org.",
            "dns_name": "myfip2",
            "created_at": "2016-12-21T11:55:50Z",
            "updated_at": "2016-12-21T11:55:53Z",
            "revision_number": 2,
            "project_id": "4969c491a3c74ee4af974e6d800c62de",
            "tenant_id": "4969c491a3c74ee4af974e6d800c62de",
            "floating_network_id": "376da547-b977-4cfe-9cba-275c80debf57",
            "fixed_ip_address": null,
            "floating_ip_address": "172.24.4.227",
            "port_id": null,
            "id": "61cea855-49cb-4846-997d-801b70c71bdd",
            "status": "DOWN",
            "port_details": null,
            "tags": ["tag1,tag2"],
            "port_forwardings": [],
            "qos_network_policy_id": "174dd0c1-a4eb-49d4-a807-ae80246d82f4",
            "qos_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae"
        },
        {
            "router_id": "0303bf18-2c52-479c-bd68-e0ad712a1639",
            "description": "for test with port forwarding",
            "dns_domain": "my-domain.org.",
            "dns_name": "myfip3",
            "created_at": "2018-06-15T02:12:48Z",
            "updated_at": "2018-06-15T02:12:57Z",
            "revision_number": 1,
            "project_id": "4969c491a3c74ee4af974e6d800c62de",
            "tenant_id": "4969c491a3c74ee4af974e6d800c62de",
            "floating_network_id": "376da547-b977-4cfe-9cba-275c80debf57",
            "fixed_ip_address": null,
            "floating_ip_address": "172.24.4.42",
            "port_id": null,
            "id": "898b198e-49f7-47d6-a7e1-53f626a548e6",
            "status": "ACTIVE",
            "tags": [],
            "port_forwardings": [
                {
                    "protocol": "tcp",
                    "internal_ip_address": "10.0.0.19",
                    "internal_port": 25,
                    "internal_port_id": "2057ec54-8be2-11eb-8dcd-0242ac130003",
                    "external_port": 2225,
                    "id": "0f23a90a-8be2-11eb-8dcd-0242ac130003"
                },
                {
                    "protocol": "tcp",
                    "internal_ip_address": "10.0.0.18",
                    "internal_port": 16666,
                    "internal_port_id": "1238be08-a2a8-4b8d-addf-fb5e2250e480",
                    "external_port": 8786,
                    "id": "e0a0274e-4d19-4eab-9e12-9e77a8caf3ea"
                }
            ],
            "qos_network_policy_id": "174dd0c1-a4eb-49d4-a807-ae80246d82f4",
            "qos_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae"
        }
    ]
}
POST
/v2.0/floatingips

Create floating IP

Creates a floating IP, and, if you specify port information, associates the floating IP with an internal port.

To associate the floating IP with an internal port, specify the port ID attribute in the request body. If you do not specify a port ID in the request, you can issue a PUT request instead of a POST request.

Default policy settings enable only administrative users to set floating IP addresses and some non-administrative users might require a floating IP address. If you do not specify a floating IP address in the request, the operation automatically allocates one.

By default, this operation associates the floating IP address with a single fixed IP address that is configured on an OpenStack Networking port. If a port has multiple IP addresses, you must specify the fixed_ip_address attribute in the request body to associate a fixed IP address with the floating IP address.

You can create floating IPs on only external networks. When you create a floating IP, you must specify the ID of the network on which you want to create the floating IP. Alternatively, you can create a floating IP on a subnet in the external network, based on the costs and quality of that subnet.

You must configure an IP address with the internal OpenStack Networking port that is associated with the floating IP address.

The operation returns the Bad Request (400) response code for one of reasons:

  • The network is not external, such as router:external=False.

  • The internal OpenStack Networking port is not associated with the floating IP address.

  • The requested floating IP address does not fall in the subnet range for the external network.

  • The fixed IP address is not valid.

If the port ID is not valid, this operation returns 404 response code.

The operation returns the Conflict (409) response code for one of reasons:

  • The requested floating IP address is already in use.

  • The internal OpenStack Networking port and fixed IP address are already associated with another floating IP.

  • The external DNS service recordset quota exceeds the limit.

Normal response codes: 201

Error response codes: 400, 401, 404, 409

Request

Name

In

Type

Description

floatingip

body

object

A floatingip object. When you associate a floating IP address with a VM, the instance has the same public IP address each time that it boots, basically to maintain a consistent IP address for maintaining DNS assignment.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

floating_network_id

body

string

The ID of the network associated with the floating IP.

fixed_ip_address (Optional)

body

string

The fixed IP address that is associated with the floating IP. If an internal port has multiple associated IP addresses, the service chooses the first IP address unless you explicitly define a fixed IP address in the fixed_ip_address parameter.

floating_ip_address (Optional)

body

string

The floating IP address.

port_id (Optional)

body

string

The ID of a port associated with the floating IP. To associate the floating IP with a fixed IP at creation time, you must specify the identifier of the internal port.

subnet_id (Optional)

body

string

The subnet ID on which you want to create the floating IP.

distributed (Optional)

body

boolean

true indicates a distributed floatingip. It is available when floating-ip-distributed extension is enabled.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

dns_domain (Optional)

body

string

A valid DNS domain.

dns_name (Optional)

body

string

A valid DNS name.

qos_policy_id (Optional)

body

string

The ID of the QoS policy associated with the floating IP.

Request Example

{
    "floatingip": {
        "floating_network_id": "376da547-b977-4cfe-9cba-275c80debf57",
        "port_id": "ce705c24-c1ef-408a-bda3-7bbd946164ab",
        "subnet_id": "278d9507-36e7-403c-bb80-1d7093318fe6",
        "fixed_ip_address": "10.0.0.3",
        "floating_ip_address": "172.24.4.228",
        "description": "floating ip for testing",
        "dns_domain": "my-domain.org.",
        "dns_name": "myfip",
        "qos_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae"
    }
}

Response Parameters

Name

In

Type

Description

floatingip

body

object

A floatingip object. When you associate a floating IP address with a VM, the instance has the same public IP address each time that it boots, basically to maintain a consistent IP address for maintaining DNS assignment.

router_id

body

string

The ID of the router for the floating IP.

status

body

string

The status of the floating IP. Values are ACTIVE, DOWN and ERROR.

description

body

string

A human-readable description for the resource.

distributed

body

boolean

true indicates a distributed floatingip. It is available when floating-ip-distributed extension is enabled.

dns_domain

body

string

A valid DNS domain.

dns_name

body

string

A valid DNS name.

port_details

body

string

The information of the port that this floating IP associates with. In particular, if the floating IP is associated with a port, this field contains some attributes of the associated port, including name, network_id, mac_address, admin_state_up, status, device_id and device_owner. If the floating IP is not associated with a port, this field is null.

tenant_id

body

string

The ID of the project.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

revision_number

body

integer

The revision number of the resource.

project_id

body

string

The ID of the project.

floating_network_id

body

string

The ID of the network associated with the floating IP.

fixed_ip_address

body

string

The fixed IP address that is associated with the floating IP address.

floating_ip_address

body

string

The floating IP address.

port_id

body

string

The ID of a port associated with the floating IP.

id

body

string

The ID of the floating IP address.

tags

body

array

The list of tags on the resource.

port_forwardings

body

array

The associated port forwarding resources for the floating IP. If the floating IP has multiple port forwarding resources, this field has multiple entries. Each entry consists of network IP protocol (protocol), the fixed IP address of internal neutron port (internal_ip_address), the TCP or UDP port or port range used by internal neutron port (internal_port) or (internal_port_range) and the TCP or UDP port or port range used by floating IP (external_port) or (external_port_range).

qos_network_policy_id

body

string

The ID of the QoS policy of the network where this floating IP is plugged.

qos_policy_id

body

string

The ID of the QoS policy associated with the floating IP.

Response Example

{
    "floatingip": {
        "fixed_ip_address": "10.0.0.3",
        "floating_ip_address": "172.24.4.228",
        "floating_network_id": "376da547-b977-4cfe-9cba-275c80debf57",
        "id": "2f245a7b-796b-4f26-9cf9-9e82d248fda7",
        "port_id": "ce705c24-c1ef-408a-bda3-7bbd946164ab",
        "router_id": "d23abc8d-2991-4a55-ba98-2aaea84cc72f",
        "status": "ACTIVE",
        "project_id": "4969c491a3c74ee4af974e6d800c62de",
        "tenant_id": "4969c491a3c74ee4af974e6d800c62de",
        "description": "floating ip for testing",
        "dns_domain": "my-domain.org.",
        "dns_name": "myfip",
        "created_at": "2016-12-21T01:36:04Z",
        "updated_at": "2016-12-21T01:36:04Z",
        "revision_number": 1,
        "port_details": {
            "status": "ACTIVE",
            "name": "",
            "admin_state_up": true,
            "network_id": "02dd8479-ef26-4398-a102-d19d0a7b3a1f",
            "device_owner": "compute:nova",
            "mac_address": "fa:16:3e:b1:3b:30",
            "device_id": "8e3941b4-a6e9-499f-a1ac-2a4662025cba"
        },
        "tags": ["tag1,tag2"],
        "port_forwardings": [],
        "qos_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae"
    }
}
GET
/v2.0/floatingips/{floatingip_id}

Show floating IP details

Shows details for a floating IP.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

This example request shows details for a floating IP in JSON format. This example also filters the result by the fixed_ip_address and floating_ip_address fields.

GET /v2.0/floatingips/{floatingip_id}?fields=fixed_ip_address
&
fields=floating_ip_address
Accept: application/json

Normal response codes: 200

Error response codes: 401, 403, 404

Request

Name

In

Type

Description

floatingip_id

path

string

The ID of the floating IP address.

Response Parameters

Name

In

Type

Description

floatingip

body

object

A floatingip object. When you associate a floating IP address with a VM, the instance has the same public IP address each time that it boots, basically to maintain a consistent IP address for maintaining DNS assignment.

router_id

body

string

The ID of the router for the floating IP.

status

body

string

The status of the floating IP. Values are ACTIVE, DOWN and ERROR.

description

body

string

A human-readable description for the resource.

distributed

body

boolean

true indicates a distributed floatingip. It is available when floating-ip-distributed extension is enabled.

dns_domain

body

string

A valid DNS domain.

dns_name

body

string

A valid DNS name.

port_details

body

string

The information of the port that this floating IP associates with. In particular, if the floating IP is associated with a port, this field contains some attributes of the associated port, including name, network_id, mac_address, admin_state_up, status, device_id and device_owner. If the floating IP is not associated with a port, this field is null.

tenant_id

body

string

The ID of the project.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

revision_number

body

integer

The revision number of the resource.

project_id

body

string

The ID of the project.

floating_network_id

body

string

The ID of the network associated with the floating IP.

fixed_ip_address

body

string

The fixed IP address that is associated with the floating IP address.

floating_ip_address

body

string

The floating IP address.

port_id

body

string

The ID of a port associated with the floating IP.

id

body

string

The ID of the floating IP address.

tags

body

array

The list of tags on the resource.

port_forwardings

body

array

The associated port forwarding resources for the floating IP. If the floating IP has multiple port forwarding resources, this field has multiple entries. Each entry consists of network IP protocol (protocol), the fixed IP address of internal neutron port (internal_ip_address), the TCP or UDP port or port range used by internal neutron port (internal_port) or (internal_port_range) and the TCP or UDP port or port range used by floating IP (external_port) or (external_port_range).

qos_network_policy_id

body

string

The ID of the QoS policy of the network where this floating IP is plugged.

qos_policy_id

body

string

The ID of the QoS policy associated with the floating IP.

Response Example

{
    "floatingip": {
        "floating_network_id": "376da547-b977-4cfe-9cba-275c80debf57",
        "router_id": "d23abc8d-2991-4a55-ba98-2aaea84cc72f",
        "fixed_ip_address": "10.0.0.3",
        "floating_ip_address": "172.24.4.228",
        "project_id": "4969c491a3c74ee4af974e6d800c62de",
        "tenant_id": "4969c491a3c74ee4af974e6d800c62de",
        "status": "ACTIVE",
        "port_id": "ce705c24-c1ef-408a-bda3-7bbd946164ab",
        "id": "2f245a7b-796b-4f26-9cf9-9e82d248fda7",
        "description": "floating ip for testing",
        "dns_domain": "my-domain.org.",
        "dns_name": "myfip",
        "created_at": "2016-12-21T01:36:04Z",
        "updated_at": "2016-12-21T01:36:04Z",
        "revision_number": 1,
        "port_details": {
            "status": "ACTIVE",
            "name": "",
            "admin_state_up": true,
            "network_id": "02dd8479-ef26-4398-a102-d19d0a7b3a1f",
            "device_owner": "compute:nova",
            "mac_address": "fa:16:3e:b1:3b:30",
            "device_id": "8e3941b4-a6e9-499f-a1ac-2a4662025cba"
        },
        "tags": ["tag1,tag2"],
        "port_forwardings": [],
        "qos_network_policy_id": "174dd0c1-a4eb-49d4-a807-ae80246d82f4",
        "qos_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae"

    }
}
PUT
/v2.0/floatingips/{floatingip_id}

Update floating IP

Updates a floating IP and its association with an internal port.

The association process is the same as the process for the create floating IP operation.

To disassociate a floating IP from a port, set the port_id attribute to null or omit it from the request body.

This example updates a floating IP:

PUT /v2.0/floatingips/{floatingip_id} Accept: application/json

Depending on the request body that you submit, this request associates a port with or disassociates a port from a floating IP.

Normal response codes: 200

Error response codes: 400, 401, 404, 409, 412

Request

Name

In

Type

Description

floatingip

body

object

A floatingip object. When you associate a floating IP address with a VM, the instance has the same public IP address each time that it boots, basically to maintain a consistent IP address for maintaining DNS assignment.

floatingip_id

path

string

The ID of the floating IP address.

port_id

body

string

The ID of a port associated with the floating IP. To associate the floating IP with a fixed IP, you must specify the ID of the internal port. To disassociate the floating IP, null should be specified.

fixed_ip_address (Optional)

body

string

The fixed IP address that is associated with the floating IP. If an internal port has multiple associated IP addresses, the service chooses the first IP address unless you explicitly define a fixed IP address in the fixed_ip_address parameter.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

distributed (Optional)

body

boolean

true indicates a distributed floatingip. It is available when floating-ip-distributed extension is enabled.

Request Example

{
    "floatingip": {
        "port_id": "fc861431-0e6c-4842-a0ed-e2363f9bc3a8"
    }
}

Request Example (disassociate)

{
    "floatingip": {
        "port_id": null
    }
}

Response Parameters

Name

In

Type

Description

floatingip

body

object

A floatingip object. When you associate a floating IP address with a VM, the instance has the same public IP address each time that it boots, basically to maintain a consistent IP address for maintaining DNS assignment.

router_id

body

string

The ID of the router for the floating IP.

status

body

string

The status of the floating IP. Values are ACTIVE, DOWN and ERROR.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

floating_network_id

body

string

The ID of the network associated with the floating IP.

fixed_ip_address

body

string

The fixed IP address that is associated with the floating IP address.

floating_ip_address

body

string

The floating IP address.

port_id

body

string

The ID of a port associated with the floating IP.

id

body

string

The ID of the floating IP address.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

revision_number

body

integer

The revision number of the resource.

description

body

string

A human-readable description for the resource.

distributed

body

boolean

true indicates a distributed floatingip. It is available when floating-ip-distributed extension is enabled.

dns_domain

body

string

A valid DNS domain.

dns_name

body

string

A valid DNS name.

port_details

body

string

The information of the port that this floating IP associates with. In particular, if the floating IP is associated with a port, this field contains some attributes of the associated port, including name, network_id, mac_address, admin_state_up, status, device_id and device_owner. If the floating IP is not associated with a port, this field is null.

tags

body

array

The list of tags on the resource.

port_forwardings

body

array

The associated port forwarding resources for the floating IP. If the floating IP has multiple port forwarding resources, this field has multiple entries. Each entry consists of network IP protocol (protocol), the fixed IP address of internal neutron port (internal_ip_address), the TCP or UDP port or port range used by internal neutron port (internal_port) or (internal_port_range) and the TCP or UDP port or port range used by floating IP (external_port) or (external_port_range).

qos_network_policy_id

body

string

The ID of the QoS policy of the network where this floating IP is plugged.

qos_policy_id

body

string

The ID of the QoS policy associated with the floating IP.

Response Example

{
    "floatingip": {
        "created_at": "2016-12-21T10:55:50Z",
        "description": "floating ip for testing",
        "dns_domain": "my-domain.org.",
        "dns_name": "myfip",
        "fixed_ip_address": "10.0.0.4",
        "floating_ip_address": "172.24.4.228",
        "floating_network_id": "376da547-b977-4cfe-9cba-275c80debf57",
        "id": "2f245a7b-796b-4f26-9cf9-9e82d248fda7",
        "port_id": "fc861431-0e6c-4842-a0ed-e2363f9bc3a8",
        "project_id": "4969c491a3c74ee4af974e6d800c62de",
        "revision_number": 3,
        "router_id": "d23abc8d-2991-4a55-ba98-2aaea84cc72f",
        "status": "ACTIVE",
        "tags": ["tag1,tag2"],
        "tenant_id": "4969c491a3c74ee4af974e6d800c62de",
        "updated_at": "2016-12-22T03:13:49Z",
        "port_details": {
            "status": "ACTIVE",
            "name": "",
            "admin_state_up": true,
            "network_id": "02dd8479-ef26-4398-a102-d19d0a7b3a1f",
            "device_owner": "compute:nova",
            "mac_address": "fa:16:3e:b1:3b:30",
            "device_id": "8e3941b4-a6e9-499f-a1ac-2a4662025cba"
        },
        "port_forwardings": [],
        "qos_network_policy_id": "174dd0c1-a4eb-49d4-a807-ae80246d82f4",
        "qos_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae"
    }
}

Response Example (disassociate)

{
    "floatingip": {
        "floating_network_id": "376da547-b977-4cfe-9cba-275c80debf57",
        "router_id": "d23abc8d-2991-4a55-ba98-2aaea84cc72f",
        "fixed_ip_address": null,
        "floating_ip_address": "172.24.4.228",
        "project_id": "4969c491a3c74ee4af974e6d800c62de",
        "tenant_id": "4969c491a3c74ee4af974e6d800c62de",
        "status": "ACTIVE",
        "port_id": null,
        "id": "2f245a7b-796b-4f26-9cf9-9e82d248fda7",
        "description": "for test",
        "created_at": "2016-12-21T10:55:50Z",
        "updated_at": "2016-12-22T03:13:49Z",
        "revision_number": 3,
        "port_details": null,
        "tags": ["tag1,tag2"],
        "port_forwardings": []
    }
}
DELETE
/v2.0/floatingips/{floatingip_id}

Delete floating IP

Deletes a floating IP and, if present, its associated port.

This example deletes a floating IP:

DELETE /v2.0/floatingips/{floatingip_id} Accept: application/json

Normal response codes: 204

Error response codes: 401, 404, 412

Request

Name

In

Type

Description

floatingip_id

path

string

The ID of the floating IP address.

Response

There is no body content for the response of a successful DELETE request.

Floating IP pools (floatingip_pools)

Lists floating IP pools.

GET
/v2.0/floatingip_pools

List floating IP Pools

Lists floating IP pools visible to the user.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Response Parameters

Name

In

Type

Description

floatingip_pools

body

array

A list of floatingip_pools objects.

subnet_id

body

string

The ID of the subnet.

network_id

body

string

The ID of the network to which the subnet belongs.

subnet_name

body

string

Human-readable name of the resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

cidr

body

string

The CIDR of the subnet.

Response Example

{
    "floatingip_pools": [
        {
            "subnet_id": "cdec285c-b157-48aa-900c-e77f6bd958e5",
            "tenant_id": "26a7980765d0414dbc1fc1f88cdb7e6e",
            "network_id": "db193ab3-96e3-4cb3-8fc5-05f4296d0324",
            "subnet_name": "public-subnet",
            "cidr": "192.0.0.0/8",
            "project_id": "26a7980765d0414dbc1fc1f88cdb7e6e"
        }
    ]
}

Floating IPs port forwarding

Lists, creates, shows details for, updates, and deletes floating IPs port forwardings.

Port forwarding with port ranges

The floating-ip-port-forwarding-port-ranges extension adds the new attributes internal_port_range and external_port_range to the floating IP port forwardings. The value of these new attributes should be a string that represents a colon separated port range. You can not use the attributes internal_port_range and external_port_range with the attributes internal_port and external_port in the same request.

Port forwarding rule description

The floating-ip-port-forwarding-description extension adds the description attribute to the floating IP port forwardings. The value of the description attribute contains a text describing the rule, which helps users to manage/find easily theirs rules.

GET
/v2.0/floatingips/{floatingip_id}/port_forwardings/{port_forwarding_id}

Show port forwarding

Shows information for a floating IP port forwarding.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 400, 404

Request

Name

In

Type

Description

floatingip_id

path

string

The ID of the floating IP address.

port_forwarding_id

path

string

The ID of the floating IP port forwarding.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

port_forwarding

body

object

A floating IP port forwarding object.

id

body

string

The ID of the floating IP port forwarding.

internal_port_id

body

string

The ID of the Neutron port associated to the floating IP port forwarding.

internal_ip_address

body

string

The fixed IPv4 address of the Neutron port associated to the floating IP port forwarding.

internal_port (Optional)

body

integer

The TCP/UDP/other protocol port number of the Neutron port fixed IP address associated to the floating ip port forwarding.

internal_port_range (Optional)

body

string

The TCP/UDP/other protocol port range of the Neutron port fixed IP address associated to the floating ip port forwarding.

external_port (Optional)

body

integer

The TCP/UDP/other protocol port number of the port forwarding’s floating IP address.

external_port_range (Optional)

body

string

The TCP/UDP/other protocol port range of the port forwarding’s floating IP address.

protocol

body

string

The IP protocol used in the floating IP port forwarding.

description (Optional)

body

string

A text describing the rule, which helps users to manage/find easily theirs rules.

Response Example

{
  "port_forwarding": {
    "protocol": "tcp",
    "internal_ip_address": "10.0.0.11",
    "internal_port": 25,
    "internal_port_id": "1238be08-a2a8-4b8d-addf-fb5e2250e480",
    "external_port": 2230,
    "description": "Some description",
    "id": "725ade3c-9760-4880-8080-8fc2dbab9acc"
  }
}
PUT
/v2.0/floatingips/{floatingip_id}/port_forwardings/{port_forwarding_id}

Update a port forwarding

Updates a floating IP port forwarding.

Normal response codes: 200

Error response codes: 400, 404

Request

Name

In

Type

Description

floatingip_id

path

string

The ID of the floating IP address.

port_forwarding_id

path

string

The ID of the floating IP port forwarding.

port_forwarding

body

object

A floating IP port forwarding object.

internal_port_id (Optional)

body

string

The ID of the Neutron port associated to the floating IP port forwarding.

internal_ip_address

body

string

The fixed IPv4 address of the Neutron port associated to the floating IP port forwarding.

internal_port (Optional)

body

integer

The TCP/UDP/other protocol port number of the Neutron port fixed IP address associated to the floating ip port forwarding.

internal_port_range (Optional)

body

string

The TCP/UDP/other protocol port range of the Neutron port fixed IP address associated to the floating ip port forwarding.

external_port (Optional)

body

integer

The TCP/UDP/other protocol port number of the port forwarding’s floating IP address.

external_port_range (Optional)

body

string

The TCP/UDP/other protocol port range of the port forwarding’s floating IP address.

protocol (Optional)

body

string

The IP protocol used in the floating IP port forwarding.

Request Example

{
  "port_forwarding": {
    "protocol": "udp",
    "internal_port": 37,
    "internal_port_id": "99889dc2-19a7-4edb-b9d0-d2ace8d1e144",
    "external_port": 1960,
    "description": "Some description"
  }
}

Response Parameters

Name

In

Type

Description

port_forwarding

body

object

A floating IP port forwarding object.

id

body

string

The ID of the floating IP port forwarding.

internal_port_id

body

string

The ID of the Neutron port associated to the floating IP port forwarding.

internal_ip_address

body

string

The fixed IPv4 address of the Neutron port associated to the floating IP port forwarding.

internal_port (Optional)

body

integer

The TCP/UDP/other protocol port number of the Neutron port fixed IP address associated to the floating ip port forwarding.

internal_port_range (Optional)

body

string

The TCP/UDP/other protocol port range of the Neutron port fixed IP address associated to the floating ip port forwarding.

external_port (Optional)

body

integer

The TCP/UDP/other protocol port number of the port forwarding’s floating IP address.

external_port_range (Optional)

body

string

The TCP/UDP/other protocol port range of the port forwarding’s floating IP address.

protocol

body

string

The IP protocol used in the floating IP port forwarding.

description (Optional)

body

string

A text describing the rule, which helps users to manage/find easily theirs rules.

Response Example

{
  "port_forwarding": {
    "protocol": "udp",
    "internal_ip_address": "10.0.0.14",
    "internal_port": 37,
    "internal_port_id": "99889dc2-19a7-4edb-b9d0-d2ace8d1e144",
    "external_port": 1960,
    "description": "Some description",
    "id": "725ade3c-9760-4880-8080-8fc2dbab9acc"
  }
}
DELETE
/v2.0/floatingips/{floatingip_id}/port_forwardings/{port_forwarding_id}

Delete a floating IP port forwarding

Deletes a floating IP port forwarding.

Normal response codes: 204

Error response codes: 404

Request

Name

In

Type

Description

floatingip_id

path

string

The ID of the floating IP address.

port_forwarding_id

path

string

The ID of the floating IP port forwarding.

Response

There is no body content for the response of a successful DELETE request.

GET
/v2.0/floatingips/{floatingip_id}/port_forwardings

List floating IP port forwardings

Lists floating IP port forwardings that the project has access to.

Default policy settings return only the port forwardings associated to floating IPs owned by the project of the user submitting the request, unless the user has administrative role.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 400, 404

Request

Name

In

Type

Description

floatingip_id

path

string

The ID of the floating IP address.

id (Optional)

query

string

Filter the list result by the ID of the resource.

internal_port_id (Optional)

query

string

Filter the list result by the ID of the internal Neutron port.

external_port (Optional)

query

integer

Filter the list result by the TCP/UDP/other protocol port number of the floating IP.

external_port_range (Optional)

query

string

Filter the list result by the TCP/UDP/other protocol port range of the floating IP.

protocol (Optional)

query

string

Filter the list result by the used protocol.

sort_key (Optional)

query

string

Sorts by a floating IP port forwarding attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • id

  • internal_port_id

  • external_port

  • external_port_range

  • protocol

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

port_forwardings

body

array

A list of floating IP port forwardings objects.

id

body

string

The ID of the floating IP port forwarding.

internal_port_id

body

string

The ID of the Neutron port associated to the floating IP port forwarding.

internal_ip_address

body

string

The fixed IPv4 address of the Neutron port associated to the floating IP port forwarding.

internal_port (Optional)

body

integer

The TCP/UDP/other protocol port number of the Neutron port fixed IP address associated to the floating ip port forwarding.

internal_port_range (Optional)

body

string

The TCP/UDP/other protocol port range of the Neutron port fixed IP address associated to the floating ip port forwarding.

external_port (Optional)

body

integer

The TCP/UDP/other protocol port number of the port forwarding’s floating IP address.

external_port_range (Optional)

body

string

The TCP/UDP/other protocol port range of the port forwarding’s floating IP address.

protocol

body

string

The IP protocol used in the floating IP port forwarding.

description (Optional)

body

string

A text describing the rule, which helps users to manage/find easily theirs rules.

Response Example

{
  "port_forwardings": [
    {
      "protocol": "tcp",
      "internal_ip_address": "10.0.0.24",
      "internal_port": 25,
      "internal_port_id": "070ef0b2-0175-4299-be5c-01fea8cca522",
      "external_port": 2229,
      "description": "Some description",
      "id": "1798dc82-c0ed-4b79-b12d-4c3c18f90eb2"
    },
    {
      "protocol": "tcp",
      "internal_ip_address": "10.0.0.11",
      "internal_port": 25,
      "internal_port_id": "1238be08-a2a8-4b8d-addf-fb5e2250e480",
      "external_port": 2230,
      "description": "",
      "id": "e0a0274e-4d19-4eab-9e12-9e77a8caf3ea"
    },
    {
      "protocol": "tcp",
      "internal_ip_address": "10.0.0.12",
      "internal_port_range": "80:90",
      "internal_port_id": "2057ec54-8be2-11eb-8dcd-0242ac130003",
      "external_port_range": "8080:8090",
      "description": "using port ranges",
      "id": "0f23a90a-8be2-11eb-8dcd-0242ac130003"
    }
  ]
}
POST
/v2.0/floatingips/{floatingip_id}/port_forwardings

Create port forwarding

Creates a floating IP port forwarding.

Normal response codes: 201

Error response codes: 400, 404

Request

Name

In

Type

Description

floatingip_id

path

string

The ID of the floating IP address.

port_forwarding

body

object

A floating IP port forwarding object.

internal_port_id

body

string

The ID of the Neutron port associated to the floating IP port forwarding.

internal_ip_address

body

string

The fixed IPv4 address of the Neutron port associated to the floating IP port forwarding.

internal_port (Optional)

body

integer

The TCP/UDP/other protocol port number of the Neutron port fixed IP address associated to the floating ip port forwarding.

internal_port_range (Optional)

body

string

The TCP/UDP/other protocol port range of the Neutron port fixed IP address associated to the floating ip port forwarding.

external_port (Optional)

body

integer

The TCP/UDP/other protocol port number of the port forwarding’s floating IP address.

external_port_range (Optional)

body

string

The TCP/UDP/other protocol port range of the port forwarding’s floating IP address.

protocol

body

string

The IP protocol used in the floating IP port forwarding.

description (Optional)

body

string

A text describing the rule, which helps users to manage/find easily theirs rules.

Request Example

{
  "port_forwarding": {
    "protocol": "tcp",
    "internal_ip_address": "10.0.0.11",
    "internal_port": 25,
    "internal_port_id": "1238be08-a2a8-4b8d-addf-fb5e2250e480",
    "external_port": 2230,
    "description": "Some description"
  }
}

Response Parameters

Name

In

Type

Description

port_forwarding

body

object

A floating IP port forwarding object.

id

body

string

The ID of the floating IP port forwarding.

internal_port_id

body

string

The ID of the Neutron port associated to the floating IP port forwarding.

internal_ip_address

body

string

The fixed IPv4 address of the Neutron port associated to the floating IP port forwarding.

internal_port (Optional)

body

integer

The TCP/UDP/other protocol port number of the Neutron port fixed IP address associated to the floating ip port forwarding.

internal_port_range (Optional)

body

string

The TCP/UDP/other protocol port range of the Neutron port fixed IP address associated to the floating ip port forwarding.

external_port (Optional)

body

integer

The TCP/UDP/other protocol port number of the port forwarding’s floating IP address.

external_port_range (Optional)

body

string

The TCP/UDP/other protocol port range of the port forwarding’s floating IP address.

protocol

body

string

The IP protocol used in the floating IP port forwarding.

description (Optional)

body

string

A text describing the rule, which helps users to manage/find easily theirs rules.

Response Example

{
  "port_forwarding": {
    "protocol": "tcp",
    "internal_ip_address": "10.0.0.11",
    "internal_port": 25,
    "internal_port_id": "1238be08-a2a8-4b8d-addf-fb5e2250e480",
    "external_port": 2230,
    "description": "Some description",
    "id": "725ade3c-9760-4880-8080-8fc2dbab9acc"
  }
}

Routers (routers)

A router is a logical entity for forwarding packets across internal subnets and NATting them on external networks through an appropriate external gateway.

This resource is provided when router extension is enabled.

Distributed virtual router extension

The dvr extension enables the functionality of configuring a router as a distributed virtual router, adding distributed parameter.

Extra routes extension

The extra route extension (extraroute) extends router resources adding a routes attribute that contains an array of route objects. Each route object has a destination and nexthop attribute representing the route. When the extraroute-atomic extension is also available you can add or remove a set of extra routes atomically on the server side. For details please see below.

Warning

By default in a router there is one route for each attached subnet. If you add an extra route that matches one of the default routes for a subnet, the existing subnet route will be overwritten. If the Neutron route is removed, the corresponding route will be removed as well. The affected subnet will subsequently lose connectivity to this router.

Extra routes (atomic) extension

The extra route atomic extension (extraroute-atomic) extends the router resource by adding two member actions (add_extraroutes / remove_extraroutes) to edit the set of extra routes atomically on the server side.

Warning

By default in a router there is one route for each attached subnet. If you add an extra route that matches one of the default routes for a subnet, the existing subnet route will be overwritten. If the Neutron route is removed, the corresponding route will be removed as well. The affected subnet will subsequently lose connectivity to this router.

HA capability for router extension (l3-ha)

The L3 HA extension l3-ha, adds the ha attribute which enables HA capability to routers when set to true.

L3 external gateway mode extension (ext-gw-mode)

The ext-gw-mode extension of the router abstraction for specifying whether SNAT should occur on the external gateway. The ext-gw-mode extension allows enabling configurable external gateway modes, adds the external_gateway_info attribute to routers and allows definitions for network_id, enable_snat and external_fixed_ips.

L3 external gateway multihoming extension (external-gateway-multihoming)

The external-gateway-multihoming extension allows a router to have multiple external gateway ports and to have a policy specified on how to handle ECMP and BFD for default routes inferred from the subnets associated with gateway ports.

L3 flavors extension (l3-flavors)

The router flavor extension (l3-flavors) adds the flavor_id attribute to routers, allowing requests to be dispatched to different drivers depending on the flavor associated with a given router.

Resource timestamps

The standard-attr-timestamp extension adds the created_at and updated_at attributes to all resources that have standard attributes.

Router admin state down before update extension

The router-admin-state-down-before-update extension adds the requirement that the administrative state of a distributed virtual router (DVR) be set to DOWN (admin_state_up=False) prior to modifying the distributed parameter of the router. The API will return an error response code of 400 if the router’s distributed attribute is modified without first setting the router’s admin_state_up=False. This extension requires the dvr extension.

Router availability zone extension

The router_availability_zone extension adds the availability_zones and availability_zone_hints attributes to routers, allowing scheduling based on availability zones and hints. This extension requires router and availability_zone extensions.

Router service type extension (router-service-type)

The router-service-type extension enables associating a service type with a router by introducing the service_type_id parameter that can be used to associate the router with an existing service-provider, see Service providers.

Tag extension

The standard-attr-tag adds Tag support for resources with standard attributes by adding the tags attribute allowing consumers to associate tags with resources.

L3 conntrack helpers extension (expose-l3-conntrack-helper)

The router conntrack helper extension (expose-l3-conntrack-helper) adds the conntrack_helpers field to routers, allowing configurable netfilter CT target rules for routers.

Router enable ndp proxy extension (router-extend-ndp-proxy)

The router-extend-ndp-proxy extension adds a enable_ndp_proxy parameter to router. If this parameter is set as false, the router don’t support ndp_proxy.

Router gateway IP QoS (qos-gateway-ip)

The qos-gateway-ip extension adds qos_policy_id to the external_gateway_info field of routers.

Router enable default route ECMP extension (enable-default-route-ecmp)

The enable-default-route-ecmp extension adds a parameter called enable_default_route_ecmp to the router resource which can be used to enable or disable automatic configuration of ECMP default routes based on the default gateways of subnets accessible from a router’s gateway ports (see the external-gateway-multihoming extension).

Router enable default route BFD extension (enable-default-route-bfd)

The enable-default-route-bfd extension adds a parameter called enable_default_route_bfd to the router resource which can be used to enable or disable automatic configuration of BFD for default routes of a router created based on the default gateways of subnets accessible from a router’s gateway ports (see enable-default-route-ecmp extension).

GET
/v2.0/routers

List routers

Lists logical routers that the project who submits the request can access.

Default policy settings return only those routers that the project who submits the request owns, unless an administrative user submits the request.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

id (Optional)

query

string

Filter the list result by the ID of the resource.

tenant_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

project_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

name (Optional)

query

string

Filter the list result by the human-readable name of the resource.

description (Optional)

query

string

Filter the list result by the human-readable description of the resource.

admin_state_up (Optional)

query

boolean

Filter the list result by the administrative state of the resource, which is up (true) or down (false).

revision_number (Optional)

query

integer

Filter the list result by the revision number of the resource.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a router attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • admin_state_up

  • flavor_id

  • id

  • name

  • status

  • tenant_id

  • project_id

tags (Optional)

query

string

A list of tags to filter the list result by. Resources that match all tags in this list will be returned. Tags in query must be separated by comma.

tags-any (Optional)

query

string

A list of tags to filter the list result by. Resources that match any tag in this list will be returned. Tags in query must be separated by comma.

not-tags (Optional)

query

string

A list of tags to filter the list result by. Resources that match all tags in this list will be excluded. Tags in query must be separated by comma.

not-tags-any (Optional)

query

string

A list of tags to filter the list result by. Resources that match any tag in this list will be excluded. Tags in query must be separated by comma.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

routers

body

array

A list of router objects.

id

body

string

The ID of the router.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

status

body

string

The router status.

external_gateway_info

body

object

The external gateway information of the router. If the router has an external gateway, this would be a dict with network_id, enable_snat, external_fixed_ips, qos_policy_id, enable_default_route_ecmp and enable_default_route_bfd. Otherwise, this would be null.

external_gateways

body

array

The list of external gateways of the router.

revision_number

body

integer

The revision number of the resource.

routes

body

array

The extra routes configuration for L3 router. A list of dictionaries with destination and nexthop parameters. It is available when extraroute extension is enabled.

destination

body

string

The destination CIDR.

nexthop

body

string

The IP address of the next hop for the corresponding destination. The next hop IP address must be a part of one of the subnets to which the router interfaces are connected.

distributed

body

boolean

true indicates a distributed router. It is available when dvr extension is enabled.

ha

body

boolean

true indicates a highly-available router. It is available when l3-ha extension is enabled.

availability_zone_hints

body

array

The availability zone candidates for the router. It is available when router_availability_zone extension is enabled.

availability_zones

body

array

The availability zone(s) for the router. It is available when router_availability_zone extension is enabled.

service_type_id

body

string

The ID of the service type associated with the router.

flavor_id

body

string

The ID of the flavor associated with the router.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

tags

body

array

The list of tags on the resource.

conntrack_helpers

body

array

The associated conntrack helper resources for the roter. If the router has multiple conntrack helper resources, this field has multiple entries. Each entry consists of netfilter conntrack helper (helper), the network protocol (protocol), the network port (port).

enable_ndp_proxy

body

boolean

Enable NDP proxy attribute. true means NDP proxy is enabled for the router, the IPv6 address of internal subnets attached to the router can be published to external by create ndp_proxy. false means NDP proxy is disabled, the IPv6 address of internal subnets attached to the router can not be published to external by ndp_proxy. It is available when router-extend-ndp-proxy extension is enabled.

enable_default_route_bfd (Optional)

body

boolean

true indicates that Neutron will enable BFD sessions for default routes inferred from the external gateway port subnets. Available when external-gateway-multihoming extension is enabled.

enable_default_route_ecmp (Optional)

body

boolean

true indicates that Neutron will add ECMP default routes if multiple are available via different gateway ports. Available when external-gateway-multihoming extension is enabled.

Response Example

{
    "routers": [
        {
            "admin_state_up": true,
            "availability_zone_hints": [],
            "availability_zones": [
                "nova"
            ],
            "created_at": "2018-03-19T19:17:04Z",
            "description": "",
            "distributed": false,
            "external_gateway_info": {
                "enable_snat": true,
                "external_fixed_ips": [
                    {
                        "ip_address": "172.24.4.3",
                        "subnet_id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf"
                    },
                    {
                        "ip_address": "2001:db8::c",
                        "subnet_id": "0c56df5d-ace5-46c8-8f4c-45fa4e334d18"
                    }
                ],
                "network_id": "ae34051f-aa6c-4c75-abf5-50dc9ac99ef3"
            },
            "flavor_id": "f7b14d9a-b0dc-4fbe-bb14-a0f4970a69e0",
            "ha": false,
            "id": "915a14a6-867b-4af7-83d1-70efceb146f9",
            "name": "router2",
            "revision_number": 1,
            "routes": [
                {
                    "destination": "179.24.1.0/24",
                    "nexthop": "172.24.3.99"
                }
            ],
            "status": "ACTIVE",
            "updated_at": "2018-03-19T19:17:22Z",
            "project_id": "0bd18306d801447bb457a46252d82d13",
            "tenant_id": "0bd18306d801447bb457a46252d82d13",
            "service_type_id": null,
            "tags": ["tag1,tag2"],
            "conntrack_helpers": [
                {
                    "protocol": "udp",
                    "helper": "tftp",
                    "port": 69
                },
                {
                    "protocol": "tcp",
                    "helper": "ftp",
                    "port": 21
                }
            ]
        },
        {
            "admin_state_up": true,
            "availability_zone_hints": [],
            "availability_zones": [
                "nova"
            ],
            "created_at": "2018-03-19T19:17:04Z",
            "description": "",
            "distributed": false,
            "external_gateway_info": {
                "enable_snat": true,
                "external_fixed_ips": [
                    {
                        "ip_address": "172.24.4.6",
                        "subnet_id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf"
                    },
                    {
                        "ip_address": "2001:db8::9",
                        "subnet_id": "0c56df5d-ace5-46c8-8f4c-45fa4e334d18"
                    }
                ],
                "network_id": "ae34051f-aa6c-4c75-abf5-50dc9ac99ef3"
            },
            "flavor_id": "f7b14d9a-b0dc-4fbe-bb14-a0f4970a69e0",
            "ha": false,
            "id": "f8a44de0-fc8e-45df-93c7-f79bf3b01c95",
            "name": "router1",
            "revision_number": 1,
            "routes": [],
            "status": "ACTIVE",
            "updated_at": "2018-03-19T19:17:22Z",
            "project_id": "0bd18306d801447bb457a46252d82d13",
            "tenant_id": "0bd18306d801447bb457a46252d82d13",
            "service_type_id": null,
            "tags": ["tag1,tag2"],
            "conntrack_helpers": [
                {
                    "protocol": "udp",
                    "helper": "tftp",
                    "port": 69
                },
                {
                    "protocol": "tcp",
                    "helper": "ftp",
                    "port": 21
                }
            ]
        }
    ]
}
POST
/v2.0/routers

Create router

Creates a logical router.

This operation creates a logical router. The logical router does not have any internal interface and it is not associated with any subnet. You can optionally specify an external gateway for a router at create time. The external gateway for the router must be plugged into an external network. An external network has its router:external extended field set to true. To specify an external gateway, the ID of the external network must be passed in the network_id parameter of the external_gateway_info attribute in the request body.

Normal response codes: 201

Error response codes: 400, 401

Request

Name

In

Type

Description

router

body

object

A router object.

tenant_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

project_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

admin_state_up (Optional)

body

boolean

The administrative state of the resource, which is up (true) or down (false). Default is true.

external_gateway_info (Optional)

body

object

The external gateway information of the router. If the router has an external gateway, this would be a dict with network_id, enable_snat, external_fixed_ips and qos_policy_id. Otherwise, this would be null.

distributed (Optional)

body

boolean

true indicates a distributed router. It is available when dvr extension is enabled.

ha (Optional)

body

boolean

true indicates a highly-available router. It is available when l3-ha extension is enabled.

availability_zone_hints (Optional)

body

array

The availability zone candidates for the router. It is available when router_availability_zone extension is enabled.

service_type_id (Optional)

body

string

The ID of the service type associated with the router.

flavor_id (Optional)

body

string

The ID of the flavor associated with the router.

enable_ndp_proxy (Optional)

body

boolean

Enable NDP proxy attribute. Default is false, To persist this attribute value, set the enable_ndp_proxy_by_default option in the neutron.conf file. It is available when router-extend-ndp-proxy extension is enabled.

enable_default_route_bfd (Optional)

body

boolean

true indicates that Neutron will enable BFD sessions for default routes inferred from the external gateway port subnets. Available when external-gateway-multihoming extension is enabled.

enable_default_route_ecmp (Optional)

body

boolean

true indicates that Neutron will add ECMP default routes if multiple are available via different gateway ports. Available when external-gateway-multihoming extension is enabled.

Request Example

{
    "router": {
        "name": "router1",
        "external_gateway_info": {
            "network_id": "ae34051f-aa6c-4c75-abf5-50dc9ac99ef3",
            "enable_snat": true,
            "external_fixed_ips": [
                {
                    "ip_address": "172.24.4.6",
                    "subnet_id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf"
                }
            ]
        },
        "admin_state_up": true
    }
}

Response Parameters

Name

In

Type

Description

router

body

object

A router object.

id

body

string

The ID of the router.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

status

body

string

The router status.

external_gateway_info

body

object

The external gateway information of the router. If the router has an external gateway, this would be a dict with network_id, enable_snat, external_fixed_ips, qos_policy_id, enable_default_route_ecmp and enable_default_route_bfd. Otherwise, this would be null.

external_gateways

body

array

The list of external gateways of the router.

revision_number

body

integer

The revision number of the resource.

routes

body

array

The extra routes configuration for L3 router. A list of dictionaries with destination and nexthop parameters. It is available when extraroute extension is enabled.

destination

body

string

The destination CIDR.

nexthop

body

string

The IP address of the next hop for the corresponding destination. The next hop IP address must be a part of one of the subnets to which the router interfaces are connected.

distributed

body

boolean

true indicates a distributed router. It is available when dvr extension is enabled.

ha

body

boolean

true indicates a highly-available router. It is available when l3-ha extension is enabled.

availability_zone_hints

body

array

The availability zone candidates for the router. It is available when router_availability_zone extension is enabled.

availability_zones

body

array

The availability zone(s) for the router. It is available when router_availability_zone extension is enabled.

service_type_id

body

string

The ID of the service type associated with the router.

flavor_id

body

string

The ID of the flavor associated with the router.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

tags

body

array

The list of tags on the resource.

conntrack_helpers

body

array

The associated conntrack helper resources for the roter. If the router has multiple conntrack helper resources, this field has multiple entries. Each entry consists of netfilter conntrack helper (helper), the network protocol (protocol), the network port (port).

enable_ndp_proxy

body

boolean

Enable NDP proxy attribute. true means NDP proxy is enabled for the router, the IPv6 address of internal subnets attached to the router can be published to external by create ndp_proxy. false means NDP proxy is disabled, the IPv6 address of internal subnets attached to the router can not be published to external by ndp_proxy. It is available when router-extend-ndp-proxy extension is enabled.

enable_default_route_bfd (Optional)

body

boolean

true indicates that Neutron will enable BFD sessions for default routes inferred from the external gateway port subnets. Available when external-gateway-multihoming extension is enabled.

enable_default_route_ecmp (Optional)

body

boolean

true indicates that Neutron will add ECMP default routes if multiple are available via different gateway ports. Available when external-gateway-multihoming extension is enabled.

Response Example

{
    "router": {
        "admin_state_up": true,
        "availability_zone_hints": [],
        "availability_zones": [
            "nova"
        ],
        "created_at": "2018-03-19T19:17:04Z",
        "description": "",
        "distributed": false,
        "external_gateway_info": {
            "enable_snat": true,
            "external_fixed_ips": [
                {
                    "ip_address": "172.24.4.6",
                    "subnet_id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf"
                }
            ],
            "network_id": "ae34051f-aa6c-4c75-abf5-50dc9ac99ef3"
        },
        "flavor_id": "f7b14d9a-b0dc-4fbe-bb14-a0f4970a69e0",
        "ha": false,
        "id": "f8a44de0-fc8e-45df-93c7-f79bf3b01c95",
        "name": "router1",
        "routes": [],
        "revision_number": 1,
        "status": "ACTIVE",
        "updated_at": "2018-03-19T19:17:22Z",
        "project_id": "0bd18306d801447bb457a46252d82d13",
        "tenant_id": "0bd18306d801447bb457a46252d82d13",
        "service_type_id": null,
        "tags": ["tag1,tag2"],
        "conntrack_helpers": []
    }
}
GET
/v2.0/routers/{router_id}

Show router details

Shows details for a router.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 403, 404

Request

Name

In

Type

Description

router_id

path

string

The ID of the router.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

router

body

object

A router object.

id

body

string

The ID of the router.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

status

body

string

The router status.

external_gateway_info

body

object

The external gateway information of the router. If the router has an external gateway, this would be a dict with network_id, enable_snat, external_fixed_ips, qos_policy_id, enable_default_route_ecmp and enable_default_route_bfd. Otherwise, this would be null.

external_gateways

body

array

The list of external gateways of the router.

revision_number

body

integer

The revision number of the resource.

routes

body

array

The extra routes configuration for L3 router. A list of dictionaries with destination and nexthop parameters. It is available when extraroute extension is enabled.

destination

body

string

The destination CIDR.

nexthop

body

string

The IP address of the next hop for the corresponding destination. The next hop IP address must be a part of one of the subnets to which the router interfaces are connected.

distributed

body

boolean

true indicates a distributed router. It is available when dvr extension is enabled.

ha

body

boolean

true indicates a highly-available router. It is available when l3-ha extension is enabled.

availability_zone_hints

body

array

The availability zone candidates for the router. It is available when router_availability_zone extension is enabled.

availability_zones

body

array

The availability zone(s) for the router. It is available when router_availability_zone extension is enabled.

service_type_id

body

string

The ID of the service type associated with the router.

flavor_id

body

string

The ID of the flavor associated with the router.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

tags

body

array

The list of tags on the resource.

conntrack_helpers

body

array

The associated conntrack helper resources for the roter. If the router has multiple conntrack helper resources, this field has multiple entries. Each entry consists of netfilter conntrack helper (helper), the network protocol (protocol), the network port (port).

enable_ndp_proxy

body

boolean

Enable NDP proxy attribute. true means NDP proxy is enabled for the router, the IPv6 address of internal subnets attached to the router can be published to external by create ndp_proxy. false means NDP proxy is disabled, the IPv6 address of internal subnets attached to the router can not be published to external by ndp_proxy. It is available when router-extend-ndp-proxy extension is enabled.

enable_default_route_bfd (Optional)

body

boolean

true indicates that Neutron will enable BFD sessions for default routes inferred from the external gateway port subnets. Available when external-gateway-multihoming extension is enabled.

enable_default_route_ecmp (Optional)

body

boolean

true indicates that Neutron will add ECMP default routes if multiple are available via different gateway ports. Available when external-gateway-multihoming extension is enabled.

Response Example

{
    "router": {
        "admin_state_up": true,
        "availability_zone_hints": [],
        "availability_zones": [
            "nova"
        ],
        "created_at": "2018-03-19T19:17:04Z",
        "description": "",
        "distributed": false,
        "external_gateway_info": {
            "enable_snat": true,
            "external_fixed_ips": [
                {
                    "ip_address": "172.24.4.6",
                    "subnet_id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf"
                },
                {
                    "ip_address": "2001:db8::9",
                    "subnet_id": "0c56df5d-ace5-46c8-8f4c-45fa4e334d18"
                }
            ],
            "network_id": "ae34051f-aa6c-4c75-abf5-50dc9ac99ef3"
        },
        "flavor_id": "f7b14d9a-b0dc-4fbe-bb14-a0f4970a69e0",
        "ha": false,
        "id": "f8a44de0-fc8e-45df-93c7-f79bf3b01c95",
        "name": "router1",
        "revision_number": 1,
        "routes": [
            {
                "destination": "179.24.1.0/24",
                "nexthop": "172.24.3.99"
            }
        ],
        "status": "ACTIVE",
        "updated_at": "2018-03-19T19:17:22Z",
        "project_id": "0bd18306d801447bb457a46252d82d13",
        "tenant_id": "0bd18306d801447bb457a46252d82d13",
        "service_type_id": null,
        "tags": ["tag1,tag2"],
        "conntrack_helpers": []
    }
}
PUT
/v2.0/routers/{router_id}

Update router

Updates a logical router.

This operation does not enable the update of router interfaces. To update a router interface, use the add router interface and remove router interface operations.

Normal response codes: 200

Error response codes: 400, 401, 404, 412

Request

Name

In

Type

Description

router

body

object

A router object.

external_gateway_info (Optional)

body

object

The external gateway information of the router. If the router has an external gateway, this would be a dict with network_id, enable_snat, external_fixed_ips and qos_policy_id. Otherwise, this would be null.

ha (Optional)

body

boolean

true indicates a highly-available router. It is available when l3-ha extension is enabled.

name

body

string

Human-readable name of the resource.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

router_id

path

string

The ID of the router.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

routes (Optional)

body

array

The extra routes configuration for L3 router. A list of dictionaries with destination and nexthop parameters. It is available when extraroute extension is enabled. Default is an empty list ([]).

distributed (Optional)

body

boolean

true indicates a distributed router. It is available when dvr extension is enabled.

enable_ndp_proxy (Optional)

body

boolean

Enable NDP proxy attribute. Default is false, To persist this attribute value, set the enable_ndp_proxy_by_default option in the neutron.conf file. It is available when router-extend-ndp-proxy extension is enabled.

enable_default_route_bfd (Optional)

body

boolean

true indicates that Neutron will enable BFD sessions for default routes inferred from the external gateway port subnets. Available when external-gateway-multihoming extension is enabled.

enable_default_route_ecmp (Optional)

body

boolean

true indicates that Neutron will add ECMP default routes if multiple are available via different gateway ports. Available when external-gateway-multihoming extension is enabled.

Request Example

{
    "router": {
        "distributed": false,
        "external_gateway_info": {
            "network_id": "ae34051f-aa6c-4c75-abf5-50dc9ac99ef3",
            "enable_snat": true,
            "external_fixed_ips": [
                {
                    "ip_address": "172.24.4.6",
                    "subnet_id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf"
                }
            ],
            "routes": [
                {
                    "destination": "179.24.1.0/24",
                    "nexthop": "172.24.3.99"
                }
            ]
        }
    }
}

Response Parameters

Name

In

Type

Description

router

body

object

A router object.

id

body

string

The ID of the router.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

status

body

string

The router status.

external_gateway_info

body

object

The external gateway information of the router. If the router has an external gateway, this would be a dict with network_id, enable_snat, external_fixed_ips, qos_policy_id, enable_default_route_ecmp and enable_default_route_bfd. Otherwise, this would be null.

external_gateways

body

array

The list of external gateways of the router.

revision_number

body

integer

The revision number of the resource.

routes

body

array

The extra routes configuration for L3 router. A list of dictionaries with destination and nexthop parameters. It is available when extraroute extension is enabled.

destination

body

string

The destination CIDR.

nexthop

body

string

The IP address of the next hop for the corresponding destination. The next hop IP address must be a part of one of the subnets to which the router interfaces are connected.

distributed

body

boolean

true indicates a distributed router. It is available when dvr extension is enabled.

ha

body

boolean

true indicates a highly-available router. It is available when l3-ha extension is enabled.

availability_zone_hints

body

array

The availability zone candidates for the router. It is available when router_availability_zone extension is enabled.

availability_zones

body

array

The availability zone(s) for the router. It is available when router_availability_zone extension is enabled.

service_type_id

body

string

The ID of the service type associated with the router.

flavor_id

body

string

The ID of the flavor associated with the router.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

tags

body

array

The list of tags on the resource.

conntrack_helpers

body

array

The associated conntrack helper resources for the roter. If the router has multiple conntrack helper resources, this field has multiple entries. Each entry consists of netfilter conntrack helper (helper), the network protocol (protocol), the network port (port).

enable_ndp_proxy

body

boolean

Enable NDP proxy attribute. true means NDP proxy is enabled for the router, the IPv6 address of internal subnets attached to the router can be published to external by create ndp_proxy. false means NDP proxy is disabled, the IPv6 address of internal subnets attached to the router can not be published to external by ndp_proxy. It is available when router-extend-ndp-proxy extension is enabled.

enable_default_route_bfd (Optional)

body

boolean

true indicates that Neutron will enable BFD sessions for default routes inferred from the external gateway port subnets. Available when external-gateway-multihoming extension is enabled.

enable_default_route_ecmp (Optional)

body

boolean

true indicates that Neutron will add ECMP default routes if multiple are available via different gateway ports. Available when external-gateway-multihoming extension is enabled.

Response Example

{
    "router": {
        "admin_state_up": true,
        "availability_zone_hints": [],
        "availability_zones": [
            "nova"
        ],
        "created_at": "2018-03-19T19:17:04Z",
        "description": "",
        "distributed": false,
        "external_gateway_info": {
            "enable_snat": true,
            "external_fixed_ips": [
                {
                    "ip_address": "172.24.4.6",
                    "subnet_id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf"
                }
            ],
            "network_id": "ae34051f-aa6c-4c75-abf5-50dc9ac99ef3"
        },
        "flavor_id": "f7b14d9a-b0dc-4fbe-bb14-a0f4970a69e0",
        "ha": false,
        "id": "f8a44de0-fc8e-45df-93c7-f79bf3b01c95",
        "name": "router1",
        "revision_number": 3,
        "routes": [
            {
                "destination": "179.24.1.0/24",
                "nexthop": "172.24.3.99"
            }
        ],
        "status": "ACTIVE",
        "updated_at": "2018-03-19T19:17:22Z",
        "project_id": "0bd18306d801447bb457a46252d82d13",
        "tenant_id": "0bd18306d801447bb457a46252d82d13",
        "service_type_id": null,
        "tags": ["tag1,tag2"],
        "conntrack_helpers": []
    }
}
DELETE
/v2.0/routers/{router_id}

Delete router

Deletes a logical router and, if present, its external gateway interface.

This operation fails if the router has attached interfaces. Use the remove router interface operation to remove all router interfaces before you delete the router.

Normal response codes: 204

Error response codes: 401, 404, 409, 412

Request

Name

In

Type

Description

router_id

path

string

The ID of the router.

Response

There is no body content for the response of a successful DELETE request.

PUT
/v2.0/routers/{router_id}/add_router_interface

Add interface to router

Adds an internal interface to a logical router. This means a specified subnet is attached to a router as an internal router interface.

Specify the ID of a subnet or port in the request body:

  • Subnet ID. The gateway IP address for the subnet is used as an IP address of the created router interface.

  • Port ID. The IP address associated with the port is used as an IP address of the created router interface.

When you specify an IPv6 subnet, this operation adds the subnet to an existing internal port with same network ID, on the router. If a port with the same network ID does not exist, this operation creates a port on the router for that subnet.

The limitation of one IPv4 subnet per router port remains, though a port can contain any number of IPv6 subnets that belong to the same network ID.

When you use the port-create command to add a port and then call router-interface-add with this port ID, this operation adds the port to the router if the following conditions are met:

  • The port has no more than one IPv4 subnet.

  • The IPv6 subnets, if any, on the port do not have same network ID as the network ID of IPv6 subnets on any other ports.

If you specify both subnet ID and port ID, this operation returns the Bad Request (400) response code.

If the port is already in use, this operation returns the Conflict (409) response code.

This operation returns a port ID that is either:

  • The same ID that is passed in the request body when a port is specified.

  • The ID of a port that this operation creates to attach the subnet to the router.

After you run this operation, the operation sets:

  • The device_id attribute of this port to the router ID

  • The device_owner attribute to network:router_interface

Normal response codes: 200

Error response codes: 400, 401, 404, 409

Request

Name

In

Type

Description

router_id

path

string

The ID of the router.

subnet_id (Optional)

body

string

The ID of the subnet. One of subnet_id or port_id must be specified.

port_id (Optional)

body

string

The ID of the port. One of subnet_id or port_id must be specified.

Request Example

{
    "subnet_id": "a2f1f29d-571b-4533-907f-5803ab96ead1"
}

or

{
    "port_id": "2dc46bcc-d1f2-4077-b99e-91ee28afaff0"
}

Response Parameters

Name

In

Type

Description

id

body

string

The ID of the router.

subnet_id

body

string

The ID of the subnet which the router interface belongs to.

subnet_ids

body

array

A list of the ID of the subnet which the router interface belongs to. The list contains only one member.

tenant_id

body

string

The ID of the project who owns the router interface.

project_id

body

string

The ID of the project who owns the router interface.

port_id

body

string

The ID of the port which represents the router interface.

network_id

body

string

Network ID which the router interface is connected to.

tags

body

array

The list of tags on the resource.

Response Example

{
    "id": "915a14a6-867b-4af7-83d1-70efceb146f9",
    "network_id": "91c013e2-d65a-474e-9177-c3e1799ca726",
    "port_id": "2dc46bcc-d1f2-4077-b99e-91ee28afaff0",
    "subnet_id": "a2f1f29d-571b-4533-907f-5803ab96ead1",
    "subnet_ids": [
        "a2f1f29d-571b-4533-907f-5803ab96ead1"
    ],
    "project_id": "0bd18306d801447bb457a46252d82d13",
    "tenant_id": "0bd18306d801447bb457a46252d82d13",
    "tags": ["tag1,tag2"]
}
PUT
/v2.0/routers/{router_id}/remove_router_interface

Remove interface from router

Deletes an internal interface from a logical router.

This operation deletes an internal router interface, which detaches a subnet from the router. If this subnet ID is the last subnet on the port, this operation deletes the port itself. You must specify either a subnet ID or port ID in the request body; the operation uses this value to identify which router interface to deletes.

You can also specify both a subnet ID and port ID. If you specify both IDs, the subnet ID must correspond to the subnet ID of the first IP address on the port. Otherwise, this operation returns the Conflict (409) response code with information about the affected router and interface.

If you try to delete the router interface for subnets that are used by one or more routes, this operation returns the Conflict (409) response. In this case, you first need to delete such routes from the router.

If the router or the subnet and port do not exist or are not visible to you, this operation returns the Not Found (404) response code. As a consequence of this operation, the operation removes the port connecting the router with the subnet from the subnet for the network.

Normal response codes: 200

Error response codes: 400, 401, 404, 409

Request

Name

In

Type

Description

router_id

path

string

The ID of the router.

subnet_id (Optional)

body

string

The ID of the subnet. One of subnet_id or port_id must be specified.

port_id (Optional)

body

string

The ID of the port. One of subnet_id or port_id must be specified.

Request Example

{
    "subnet_id": "a2f1f29d-571b-4533-907f-5803ab96ead1"
}

or

{
    "port_id": "2dc46bcc-d1f2-4077-b99e-91ee28afaff0"
}

Response Parameters

Name

In

Type

Description

id

body

string

The ID of the router.

subnet_id

body

string

The ID of the subnet which the router interface belongs to.

subnet_ids

body

array

A list of the ID of the subnet which the router interface belongs to. The list contains only one member.

tenant_id

body

string

The ID of the project who owns the router interface.

project_id

body

string

The ID of the project who owns the router interface.

port_id

body

string

The ID of the port which represents the router interface.

network_id

body

string

Network ID which the router interface is connected to.

tags

body

array

The list of tags on the resource.

Response Example

{
    "id": "915a14a6-867b-4af7-83d1-70efceb146f9",
    "network_id": "91c013e2-d65a-474e-9177-c3e1799ca726",
    "port_id": "a5b7d209-dc02-4c46-a51f-805eadd3de64",
    "subnet_id": "4e5fe97c-82bc-432e-87d8-06d7e157dffa",
    "subnet_ids": [
        "4e5fe97c-82bc-432e-87d8-06d7e157dffa"
    ],
    "project_id": "0bd18306d801447bb457a46252d82d13",
    "tags": ["tag1,tag2"],
    "tenant_id": "0bd18306d801447bb457a46252d82d13"
}
PUT
/v2.0/routers/{router_id}/add_extraroutes

Add extra routes to router

Atomically adds a set of extra routes to the router’s already existing extra routes.

This operation is a variation on updating the router’s routes parameter. In all ways it works the same, except the extra routes sent in the request body do not replace the existing set of extra routes. Instead the extra routes sent are added to the existing set of extra routes.

The use of the add_extraroutes/remove_extraroutes member actions is preferred to updating the routes attribute in all cases when concurrent updates to the set of extra routes are possible.

The addition’s corner cases behave the following way:

  • When (destinationA, nexthopA) is to be added but it is already present that is accepted and the request succeeds.

  • Two or more routes with the same destination but with different nexthops are all accepted.

  • A route whose destination overlaps the destination of existing routes (e.g. 192.168.1.0/24 and 192.168.1.0/22) can be added and existing routes are left untouched.

The format of the request body is the same as the format of a PUT request to the router changing the routes parameter only.

The response codes and response body are the same as to the update of the routes parameter. That is the whole router object is returned including the routes parameter which represents the result of the addition.

Normal response codes: 200

Error response codes: 400, 401, 404, 412

Request

Name

In

Type

Description

router_id

path

string

The ID of the router.

routes

body

array

The extra routes configuration for L3 router. A list of dictionaries with destination and nexthop parameters. It is available when extraroute extension is enabled.

Request Example

{
   "router" : {
      "routes" : [
         { "destination" : "10.0.3.0/24", "nexthop" : "10.0.0.13" },
         { "destination" : "10.0.4.0/24", "nexthop" : "10.0.0.14" }
      ]
   }
}

Response Parameters

Name

In

Type

Description

id

body

string

The ID of the router.

name

path

string

The name of the router.

routes

body

array

The extra routes configuration for L3 router. A list of dictionaries with destination and nexthop parameters. It is available when extraroute extension is enabled.

Response Example

{
   "router" : {
      "id" : "64e339bb-1a6c-47bd-9ee7-a0cf81a35172",
      "name" : "router1",
      "routes" : [
         { "destination" : "10.0.1.0/24", "nexthop" : "10.0.0.11" },
         { "destination" : "10.0.2.0/24", "nexthop" : "10.0.0.12" },
         { "destination" : "10.0.3.0/24", "nexthop" : "10.0.0.13" },
         { "destination" : "10.0.4.0/24", "nexthop" : "10.0.0.14" }
      ]
   }
}
PUT
/v2.0/routers/{router_id}/remove_extraroutes

Remove extra routes from router

Atomically removes a set of extra routes from the router’s already existing extra routes.

This operation is a variation on updating the router’s routes parameter. In all ways it works the same, except the extra routes sent in the request body do not replace the existing set of extra routes. Instead the the extra routes sent are removed from the existing set of extra routes.

The use of the add_extraroutes/remove_extraroutes member actions is preferred to updating the routes attribute in all cases when concurrent updates to the set of extra routes are possible.

The removal’s corner cases behave the following way:

  • An extra route is only removed if there is an exact match (including the destination and nexthop) between the route sent and the route already present.

  • When (destinationA, nexthopA) is to be removed but it is already missing that is accepted and the request succeeds.

The format of the request body is the same as the format of a PUT request to the router changing the routes parameter only. However the routes sent are not meant to overwrite the whole routes parameter, but they are meant to be removed from the existing set.

The response codes and response body are the same as to the update of the routes parameter. That is the whole router object is returned including the routes parameter which represents the result of the removal.

Normal response codes: 200

Error response codes: 400, 401, 404, 412

Request

Name

In

Type

Description

router_id

path

string

The ID of the router.

routes

body

array

The extra routes configuration for L3 router. A list of dictionaries with destination and nexthop parameters. It is available when extraroute extension is enabled.

Request Example

{
   "router" : {
      "routes" : [
         { "destination" : "10.0.3.0/24", "nexthop" : "10.0.0.13" },
         { "destination" : "10.0.4.0/24", "nexthop" : "10.0.0.14" }
      ]
   }
}

Response Parameters

Name

In

Type

Description

id

body

string

The ID of the router.

name

path

string

The name of the router.

routes

body

array

The extra routes configuration for L3 router. A list of dictionaries with destination and nexthop parameters. It is available when extraroute extension is enabled.

Response Example

{
   "router" : {
      "id" : "64e339bb-1a6c-47bd-9ee7-a0cf81a35172",
      "name" : "router1",
      "routes" : [
         { "destination" : "10.0.1.0/24", "nexthop" : "10.0.0.11" },
         { "destination" : "10.0.2.0/24", "nexthop" : "10.0.0.12" }
      ]
   }
}
PUT
/v2.0/routers/{router_id}/add_external_gateways

Add external gateways to router

Add external gateways to a router in addition to the ones it already has.

Multiple gateways attached to the same network can be added to the same router.

The add/update/remove external gateways operations extend the use of router.external_gateway_info to manage multiple external gateways. The full set of external gateways is exposed in the read-only router.external_gateways parameter. router.external_gateways contains a list of external_gateway_info structures like:

[
  {"network_id": ...,
   "external_fixed_ips": [{"ip_address": ..., "subnet_id": ...}, ...],
   "enable_snat": ...},
  ...
]

The first item (index 0) of the external_gateways list is special if a router does not have any gateway ports yet:

  • It will provide data for the compatibility router.external_gateway_info field of a router;

  • This first item sets a router’s default route. If ECMP is enabled for default routes inferred from gateway port subnets, then all of those default routes are used for load-sharing;

  • The first item is just another extra gateway if the add operation is performed when a router already has one or more gateways.

The order of the the rest of the list (indexes 1, 2, …) is irrelevant and ignored.

The first external gateway can be managed in two ways: via router.external_gateway_info or via add/update/remove_external_gateways. The other external gateways can only be managed via add/update/remove_external_gateways.

The format of the request body is the same as the format of the read-only router.external_gateways parameter, but wrapped as follows:

{"router": {"external_gateways": EXTERNAL-GATEWAY-LIST}}

The response codes and response body are the same as to the update of the router. That is the whole router object is returned including the external_gateway_info and external_gateways parameters which represents the result of the operation.

Changes in router.external_gateway_info are reflected in router.external_gateways and vice versa. Updating external_gateway_info also updates the first element of external_gateways and it leaves the rest of external_gateways unchanged. Setting external_gateway_info to an empty value removes a single gateway and one of the extra gateways takes its place instead.

Normal response codes: 200

Error response codes: 400, 401, 404, 412

Request Parameters

Name

In

Type

Description

router_id

path

string

The ID of the router.

external_gateways

body

array

The list of external gateways of the router.

Request Example

{
   "router" : {
      "external_gateways" : [
         {
            "enable_snat" : false,
            "external_fixed_ips" : [
               {
                  "ip_address" : "192.0.2.2",
                  "subnet_id" : "b189c314-ebb9-11eb-939c-9bde3f3867cb"
               }
            ],
            "network_id" : "8edec774-ebb9-11eb-9b09-371108ef5905"
         }
      ]
   }
}

Response Parameters

Name

In

Type

Description

id

body

string

The ID of the router.

name

path

string

The name of the router.

external_gateways

body

array

The list of external gateways of the router.

Response Example

{
   "router" : {
      "admin_state_up" : true,
      "availability_zone_hints" : [],
      "availability_zones" : [
         "nova"
      ],
      "created_at" : "2021-06-29T13:33:40Z",
      "description" : "",
      "distributed" : false,
      "enable_default_route_ecmp" : false,
      "enable_default_route_bfd" : false,
      "external_gateway_info" : {
         "enable_snat" : false,
         "external_fixed_ips" : [
            {
               "ip_address" : "172.24.4.144",
               "subnet_id" : "1ed1c499-a45d-48d0-a567-e83a2364a40e"
            }
         ],
         "network_id" : "52700ca1-1647-46ad-8f86-b9e64eaed820"
      },
      "external_gateways" : [
         {
            "enable_snat" : false,
            "external_fixed_ips" : [
               {
                  "ip_address" : "172.24.4.144",
                  "subnet_id" : "1ed1c499-a45d-48d0-a567-e83a2364a40e"
               }
            ],
            "network_id" : "52700ca1-1647-46ad-8f86-b9e64eaed820"
         },
         {
            "enable_snat" : false,
            "external_fixed_ips" : [
               {
                  "ip_address" : "192.0.2.2",
                  "subnet_id" : "b189c314-ebb9-11eb-939c-9bde3f3867cb"
               }
            ],
            "network_id" : "8edec774-ebb9-11eb-9b09-371108ef5905"
         }
      ],
      "flavor_id" : null,
      "ha" : false,
      "id" : "47c32c39-1c09-47de-8d50-ec57a96db5e7",
      "interfaces_info" : [
         {
            "ip_address" : "fd26:d08e:af31::1",
            "port_id" : "20683e3d-b041-4977-9686-b97db622c76a",
            "subnet_id" : "2921b809-b60a-4799-ac99-59dacbeb7c3a"
         },
         {
            "ip_address" : "10.0.0.1",
            "port_id" : "89ab7084-7883-48e6-8281-d498a0cf4c92",
            "subnet_id" : "3a5bec20-2df1-4d11-b0d5-5481969b91ac"
         },
         {
            "ip_address" : "10.0.5.1",
            "port_id" : "b04c6f4e-5bc7-43a2-85e9-c28452368532",
            "subnet_id" : "f96970c4-026a-46f3-9852-f512a56688fe"
         }
      ],
      "name" : "router1",
      "project_id" : "b66a1cea961f49738fff1210733ec440",
      "revision_number" : 7,
      "routes" : [],
      "status" : "ACTIVE",
      "tags" : [],
      "updated_at" : "2021-06-29T13:37:07Z"
   }
}
PUT
/v2.0/routers/{router_id}/update_external_gateways

Update external gateways of router

Update some external gateways of router.

For general information on the add/update/remove external gateways operations see add_external_gateways above.

The external gateways to be updated are identified by the network_ids found in the PUT request. The external_fixed_ips, enable_snat, fields can be updated. The network_id field cannot be updated - any changes will cause a gateway port to be removed and recreated.

The format of the request body is the same as the format of the read-only router.external_gateways parameter, but wrapped as follows:

{"router": {"external_gateways": EXTERNAL-GATEWAY-LIST}}

The enable_snat field does not have any effect for extra gateways except for the first external gateway in the list.

The network_id field is used to identify a particular gateway port along with the external_fixed_ips field. Specifying just the network_id field is ambiguous: Neutron will attempt to find the matching gateway port but if there are multiple matches it will return an error response code.

The enable_snat field can be omitted from the request. Specifying external_fixed_ips will result in matching ports based on those fixed IPs. If a gateway port has a subset of the specified fixed IPs, then the set of IPs will be updated to match the ones in the request. Alternatively, if a gateway port has a superset of fixed IPs from the request the IPs will be removed from the gateway port.

The response codes and response body are the same as to the update of the router. That is the whole router object is returned including the external_gateway_info and external_gateways parameters which represents the result of the operation.

Please note that updating external_gateway_info also updates the first element of external_gateways and it leaves the rest of external_gateways unchanged.

Normal response codes: 200

Error response codes: 400, 401, 404, 412

Request Parameters

Name

In

Type

Description

router_id

path

string

The ID of the router.

external_gateways

body

array

The list of external gateways of the router.

Request Example

{
   "router" : {
      "external_gateways" : [
         {
            "enable_snat" : true,
            "network_id" : "8edec774-ebb9-11eb-9b09-371108ef5905"
         }
      ]
   }
}

Response Parameters

Name

In

Type

Description

id

body

string

The ID of the router.

name

path

string

The name of the router.

external_gateways

body

array

The list of external gateways of the router.

Response Example

{
   "router" : {
      "admin_state_up" : true,
      "availability_zone_hints" : [],
      "availability_zones" : [
         "nova"
      ],
      "created_at" : "2021-06-29T13:33:40Z",
      "description" : "",
      "distributed" : false,
      "enable_default_route_ecmp" : false,
      "enable_default_route_bfd" : false,
      "external_gateway_info" : {
         "enable_snat" : false,
         "enable_default_route_ecmp": false,
         "enable_default_route_bfd": false,
         "external_fixed_ips" : [
            {
               "ip_address" : "172.24.4.144",
               "subnet_id" : "1ed1c499-a45d-48d0-a567-e83a2364a40e"
            }
         ],
         "network_id" : "52700ca1-1647-46ad-8f86-b9e64eaed820"
      },
      "external_gateways" : [
         {
            "enable_snat" : false,
            "external_fixed_ips" : [
               {
                  "ip_address" : "172.24.4.144",
                  "subnet_id" : "1ed1c499-a45d-48d0-a567-e83a2364a40e"
               }
            ],
            "network_id" : "52700ca1-1647-46ad-8f86-b9e64eaed820"
         },
         {
            "enable_snat" : true,
            "external_fixed_ips" : [
               {
                  "ip_address" : "192.0.2.2",
                  "subnet_id" : "b189c314-ebb9-11eb-939c-9bde3f3867cb"
               }
            ],
            "network_id" : "8edec774-ebb9-11eb-9b09-371108ef5905"
         }
      ],
      "flavor_id" : null,
      "ha" : false,
      "id" : "47c32c39-1c09-47de-8d50-ec57a96db5e7",
      "interfaces_info" : [
         {
            "ip_address" : "fd26:d08e:af31::1",
            "port_id" : "20683e3d-b041-4977-9686-b97db622c76a",
            "subnet_id" : "2921b809-b60a-4799-ac99-59dacbeb7c3a"
         },
         {
            "ip_address" : "10.0.0.1",
            "port_id" : "89ab7084-7883-48e6-8281-d498a0cf4c92",
            "subnet_id" : "3a5bec20-2df1-4d11-b0d5-5481969b91ac"
         },
         {
            "ip_address" : "10.0.5.1",
            "port_id" : "b04c6f4e-5bc7-43a2-85e9-c28452368532",
            "subnet_id" : "f96970c4-026a-46f3-9852-f512a56688fe"
         }
      ],
      "name" : "router1",
      "project_id" : "b66a1cea961f49738fff1210733ec440",
      "revision_number" : 7,
      "routes" : [],
      "status" : "ACTIVE",
      "tags" : [],
      "updated_at" : "2021-06-29T13:37:07Z"
   }
}
PUT
/v2.0/routers/{router_id}/remove_external_gateways

Remove external gateways from router

Remove some external gateways from router.

For general information on the add/update/remove external gateways operations see add_external_gateways above.

The format of the request body is the same as the format of the read-only router.external_gateways parameter, but wrapped as follows:

{"router": {"external_gateways": EXTERNAL-GATEWAY-LIST}}

However the request body can be partial. Only the network_id and external_fixed_ips fields from the external_gateway_info structure is used in order to match the specific gateway ports. The enable_snat key can be present but its value is ignored.

Please note that setting external_gateway_info to an empty value also resets external_gateways to the empty list.

Normal response codes: 200

Error response codes: 400, 401, 404, 412

Request Parameters

Name

In

Type

Description

router_id

path

string

The ID of the router.

external_gateways

body

array

The list of external gateways of the router.

Request Example

{
   "router" : {
      "external_gateways" : [
         {
            "network_id" : "8edec774-ebb9-11eb-9b09-371108ef5905"
         }
      ]
   }
}

Response Parameters

Name

In

Type

Description

id

body

string

The ID of the router.

name

path

string

The name of the router.

external_gateways

body

array

The list of external gateways of the router.

Response Example

{
   "router" : {
      "admin_state_up" : true,
      "availability_zone_hints" : [],
      "availability_zones" : [
         "nova"
      ],
      "created_at" : "2021-06-29T13:33:40Z",
      "description" : "",
      "distributed" : false,
      "enable_default_route_ecmp" : false,
      "enable_default_route_bfd" : false,
      "external_gateway_info" : {
         "enable_snat" : false,
         "external_fixed_ips" : [
            {
               "ip_address" : "172.24.4.144",
               "subnet_id" : "1ed1c499-a45d-48d0-a567-e83a2364a40e"
            }
         ],
         "network_id" : "52700ca1-1647-46ad-8f86-b9e64eaed820"
      },
      "external_gateways" : [
         {
            "enable_snat" : false,
            "external_fixed_ips" : [
               {
                  "ip_address" : "172.24.4.144",
                  "subnet_id" : "1ed1c499-a45d-48d0-a567-e83a2364a40e"
               }
            ],
            "network_id" : "52700ca1-1647-46ad-8f86-b9e64eaed820"
         }
      ],
      "flavor_id" : null,
      "ha" : false,
      "id" : "47c32c39-1c09-47de-8d50-ec57a96db5e7",
      "interfaces_info" : [
         {
            "ip_address" : "fd26:d08e:af31::1",
            "port_id" : "20683e3d-b041-4977-9686-b97db622c76a",
            "subnet_id" : "2921b809-b60a-4799-ac99-59dacbeb7c3a"
         },
         {
            "ip_address" : "10.0.0.1",
            "port_id" : "89ab7084-7883-48e6-8281-d498a0cf4c92",
            "subnet_id" : "3a5bec20-2df1-4d11-b0d5-5481969b91ac"
         },
         {
            "ip_address" : "10.0.5.1",
            "port_id" : "b04c6f4e-5bc7-43a2-85e9-c28452368532",
            "subnet_id" : "f96970c4-026a-46f3-9852-f512a56688fe"
         }
      ],
      "name" : "router1",
      "project_id" : "b66a1cea961f49738fff1210733ec440",
      "revision_number" : 7,
      "routes" : [],
      "status" : "ACTIVE",
      "tags" : [],
      "updated_at" : "2021-06-29T13:37:07Z"
   }
}

Router NDP proxy (ndp_proxies)

A ndp_proxy is a logical entity for annunciate a unique IPv6 address to external network. It depends on a router entity on which external gateway is enabled.

GET
/v2.0/ndp_proxies

List ndp proxies

Lists logical ndp_proxies that the project who submits the request can access.

Default policy settings return only those ndp_proxies that the project who submits the request owns, unless an administrative user submits the request.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

id (Optional)

query

string

Filter the list result by the ID of the resource.

tenant_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

project_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

name (Optional)

query

string

Filter the list result by the human-readable name of the resource.

description (Optional)

query

string

Filter the list result by the human-readable description of the resource.

router_id (Optional)

query

string

The ID of the router for the ndp proxy.

port_id (Optional)

query

string

The ID of the port for the ndp proxy.

ip_address (Optional)

query

string

The IPv6 address which the ndp proxy annunciate to external network.

revision_number (Optional)

query

integer

Filter the list result by the revision number of the resource.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a ndp proxy attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • id

  • name

  • tenant_id

  • project_id

  • router_id

  • port_id

  • ip_address

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

ndp_proxies

body

array

A list of ndp proxy object.

name

body

string

Human-readable name of the resource.

id

body

string

The ID of the ndp proxy

description

body

string

A human-readable description for the resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

revision_number

body

integer

The revision number of the resource.

router_id

body

string

The ID of the router for the ndp proxy.

port_id

body

string

The ID of the port for the ndp proxy.

ip_address

body

string

The IPv6 address which the ndp proxy annunciate to external network.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

Response Example

{
  "ndp_proxies": [
    {
      "name": "proxy1",
      "id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf",
      "router_id": "915a14a6-867b-4af7-83d1-70efceb146f9",
      "port_id": "f7b14d9a-b0dc-4fbe-bb14-a0f4970a69e0",
      "ip_address": "2001::1:56",
      "revision_number": 1,
      "project_id": "0bd18306d801447bb457a46252d82d13",
      "tenant_id": "0bd18306d801447bb457a46252d82d13",
      "created_at": "2021-07-16T19:17:04Z",
      "updated_at": "2021-07-16T20:36:22Z",
      "description": ""
    },
    {
      "name": "proxy2",
      "id": "f8a44de0-fc8e-45df-93c7-f79bf3b01c95",
      "router_id": "915a14a6-867b-4af7-83d1-70efceb146f9",
      "port_id": "fc36c5b0-497b-42a3-8ef3-545f90756a41",
      "ip_address": "2001::1:67",
      "revision_number": 1,
      "project_id": "0bd18306d801447bb457a46252d82d13",
      "tenant_id": "0bd18306d801447bb457a46252d82d13",
      "created_at": "2021-07-16T19:27:04Z",
      "updated_at": "2021-07-16T20:38:22Z",
      "description": ""
    }
  ]
}
GET
/v2.0/ndp_proxies/{ndp_proxy_id}

Show ndp proxy details

Shows information for a ndp proxy

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

ndp_proxy_id

path

string

The ID of the ndp proxy.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

ndp_proxy

body

object

A ndp proxy object.

name

body

string

Human-readable name of the resource.

id

body

string

The ID of the ndp proxy

description

body

string

A human-readable description for the resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

revision_number

body

integer

The revision number of the resource.

router_id

body

string

The ID of the router for the ndp proxy.

port_id

body

string

The ID of the port for the ndp proxy.

ip_address

body

string

The IPv6 address which the ndp proxy annunciate to external network.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

Response Example

{
  "ndp_proxy": {
    "name": "proxy1",
    "id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf",
    "router_id": "915a14a6-867b-4af7-83d1-70efceb146f9",
    "port_id": "f7b14d9a-b0dc-4fbe-bb14-a0f4970a69e0",
    "ip_address": "2001::1:56",
    "revision_number": 1,
    "project_id": "0bd18306d801447bb457a46252d82d13",
    "tenant_id": "0bd18306d801447bb457a46252d82d13",
    "created_at": "2021-07-16T19:17:04Z",
    "updated_at": "2021-07-16T20:36:22Z",
    "description": ""
  }
}
PUT
/v2.0/ndp_proxies/{ndp_proxy_id}

Update a ndp proxy

Updates a ndp proxy

Normal response codes: 200

Error response codes: 400, 401, 404

Request

Name

In

Type

Description

ndp_proxy_id

path

string

The ID of the ndp proxy.

ndp_proxy

body

object

A ndp proxy object.

name

body

string

Human-readable name of the resource.

description (Optional)

body

string

A human-readable description for the resource.

Request Example

{
  "ndp_proxy": {
    "name": "new-name",
    "description": "balabalabala"
  }
}

Response Parameters

Name

In

Type

Description

ndp_proxy

body

object

A ndp proxy object.

name

body

string

Human-readable name of the resource.

id

body

string

The ID of the ndp proxy

description

body

string

A human-readable description for the resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

revision_number

body

integer

The revision number of the resource.

router_id

body

string

The ID of the router for the ndp proxy.

port_id

body

string

The ID of the port for the ndp proxy.

ip_address

body

string

The IPv6 address which the ndp proxy annunciate to external network.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

Response Example

{
  "ndp_proxy": {
    "name": "new-name",
    "id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf",
    "router_id": "915a14a6-867b-4af7-83d1-70efceb146f9",
    "port_id": "f7b14d9a-b0dc-4fbe-bb14-a0f4970a69e0",
    "ip_address": "2001::1:56",
    "revision_number": 3,
    "project_id": "0bd18306d801447bb457a46252d82d13",
    "tenant_id": "0bd18306d801447bb457a46252d82d13",
    "created_at": "2021-07-16T19:17:04Z",
    "updated_at": "2021-07-16T20:36:22Z",
    "description": "balabalabala"
  }
}
POST
/v2.0/ndp_proxies

Create ndp proxy

Creates a ndp proxy

Normal response codes: 201

Error response codes: 400, 401

Request

Name

In

Type

Description

ndp_proxy

body

object

A ndp proxy object.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

router_id

body

string

The ID of the router for the ndp proxy.

port_id

body

string

The ID of the port for the ndp proxy.

ip_address (Optional)

body

string

The IPv6 address which the ndp proxy annunciate to external network.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

Request Example

{
  "ndp_proxy": {
    "name": "ndp_proxy1",
    "router_id": "1238be08-a2a8-4b8d-addf-fb5e2250e480",
    "port_id": "6738be23-a398-445d-aaaf-785e4550e4cb",
    "ip_address": "2001::1:6",
    "description": "Some description"
  }
}

Response Parameters

Name

In

Type

Description

ndp_proxy

body

object

A ndp proxy object.

name

body

string

Human-readable name of the resource.

id

body

string

The ID of the ndp proxy

description

body

string

A human-readable description for the resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

revision_number

body

integer

The revision number of the resource.

router_id

body

string

The ID of the router for the ndp proxy.

port_id

body

string

The ID of the port for the ndp proxy.

ip_address

body

string

The IPv6 address which the ndp proxy annunciate to external network.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

Response Example

{
  "ndp_proxy": {
    "name": "ndp_proxy1",
    "id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf",
    "router_id": "1238be08-a2a8-4b8d-addf-fb5e2250e480",
    "port_id": "6738be23-a398-445d-aaaf-785e4550e4cb",
    "ip_address": "2001::1:6",
    "revision_number": 0,
    "project_id": "0bd18306d801447bb457a46252d82d13",
    "tenant_id": "0bd18306d801447bb457a46252d82d13",
    "created_at": "2021-07-16T19:17:04Z",
    "updated_at": "2021-07-16T20:36:22Z",
    "description": "Some description"
  }
}
DELETE
/v2.0/ndp_proxies/{ndp_proxy_id}

Delete a ndp proxy

Deletes a ndp proxy.

Normal response codes: 204

Error response codes: 404

Request

Name

In

Type

Description

ndp_proxy_id

path

string

The ID of the ndp proxy.

Response

There is no body content for the response of a successful DELETE request.

Subnet pools extension (subnetpools)

Lists, creates, shows details for, updates, and deletes subnet pools.

Address Scopes Extension

The address-scope extension adds the address_scope_id attribute to subnet pools. address_scope_id is the ID of the address scope that the subnet pool belongs to.

Resource timestamps

The standard-attr-timestamp extension adds the created_at and updated_at attributes to all resources that have standard attributes.

Tag extension

The standard-attr-tag adds Tag support for resources with standard attributes by adding the tags attribute allowing consumers to associate tags with resources.

GET
/v2.0/subnetpools/{subnetpool_id}

Show subnet pool

Shows information for a subnet pool.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

subnetpool_id

path

string

The UUID of the subnet pool.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

subnetpool

body

object

A subnetpool object.

id

body

string

The ID of the subnet pool.

name

body

string

Human-readable name of the resource.

default_quota (Optional)

body

integer

A per-project quota on the prefix space that can be allocated from the subnet pool for project subnets. Default is no quota is enforced on allocations from the subnet pool. For IPv4 subnet pools, default_quota is measured in units of /32. For IPv6 subnet pools, default_quota is measured units of /64. All projects that use the subnet pool have the same prefix quota applied.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

prefixes

body

array

A list of subnet prefixes to assign to the subnet pool. The API merges adjacent prefixes and treats them as a single prefix. Each subnet prefix must be unique among all subnet prefixes in all subnet pools that are associated with the address scope.

min_prefixlen (Optional)

body

integer

The smallest prefix that can be allocated from a subnet pool. For IPv4 subnet pools, default is 8. For IPv6 subnet pools, default is 64.

address_scope_id (Optional)

body

object

An address scope to assign to the subnet pool.

ip_version (Optional)

body

integer

The IP protocol version. Valid value is 4 or 6. Default is 4.

shared (Optional)

body

boolean

Indicates whether this resource is shared across all projects. By default, only administrative users can change this value.

default_prefixlen (Optional)

body

integer

The size of the prefix to allocate when the cidr or prefixlen attributes are omitted when you create the subnet. Default is min_prefixlen.

max_prefixlen (Optional)

body

integer

The maximum prefix size that can be allocated from the subnet pool. For IPv4 subnet pools, default is 32. For IPv6 subnet pools, default is 128.

description

body

string

A human-readable description for the resource.

is_default

body

boolean

The subnetpool is default pool or not.

revision_number

body

integer

The revision number of the resource.

tags

body

array

The list of tags on the resource.

Response Example

{
    "subnetpool": {
        "min_prefixlen": "64",
        "address_scope_id": null,
        "default_prefixlen": "64",
        "id": "03f761e6-eee0-43fc-a921-8acf64c14988",
        "max_prefixlen": "64",
        "name": "my-subnet-pool",
        "default_quota": null,
        "is_default": false,
        "project_id": "9fadcee8aa7c40cdb2114fff7d569c08",
        "tenant_id": "9fadcee8aa7c40cdb2114fff7d569c08",
        "created_at": "2016-03-08T20:19:41",
        "prefixes": [
            "2001:db8:0:2::/64",
            "2001:db8::/63"
        ],
        "updated_at": "2016-03-08T20:19:41",
        "ip_version": 6,
        "shared": false,
        "description": "",
        "revision_number": 2,
        "tags": ["tag1,tag2"]
    }
}
PUT
/v2.0/subnetpools/{subnetpool_id}

Update subnet pool

Updates a subnet pool.

Normal response codes: 200

Error response codes: 400, 401, 403, 404, 412

Request

Name

In

Type

Description

subnetpool_id

path

string

The UUID of the subnet pool.

subnetpool

body

object

A subnetpool object.

name

body

string

Human-readable name of the resource.

default_quota (Optional)

body

integer

A per-project quota on the prefix space that can be allocated from the subnet pool for project subnets. Default is no quota is enforced on allocations from the subnet pool. For IPv4 subnet pools, default_quota is measured in units of /32. For IPv6 subnet pools, default_quota is measured units of /64. All projects that use the subnet pool have the same prefix quota applied.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

prefixes

body

array

A list of subnet prefixes to assign to the subnet pool. The API merges adjacent prefixes and treats them as a single prefix. Each subnet prefix must be unique among all subnet prefixes in all subnet pools that are associated with the address scope.

min_prefixlen (Optional)

body

integer

The smallest prefix that can be allocated from a subnet pool. For IPv4 subnet pools, default is 8. For IPv6 subnet pools, default is 64.

address_scope_id (Optional)

body

object

An address scope to assign to the subnet pool.

default_prefixlen (Optional)

body

integer

The size of the prefix to allocate when the cidr or prefixlen attributes are omitted when you create the subnet. Default is min_prefixlen.

max_prefixlen (Optional)

body

integer

The maximum prefix size that can be allocated from the subnet pool. For IPv4 subnet pools, default is 32. For IPv6 subnet pools, default is 128.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

is_default (Optional)

body

boolean

The subnetpool is default pool or not.

Request Example

{
    "subnetpool": {
        "name": "my-new-subnetpool-name",
        "prefixes": [
            "2001:db8::/64",
            "2001:db8:0:1::/64",
            "2001:db8:0:2::/64"
        ],
        "min_prefixlen": 64,
        "default_prefixlen": 64,
        "max_prefixlen": 64
    }
}

Response Parameters

Name

In

Type

Description

subnetpool

body

object

A subnetpool object.

id

body

string

The ID of the subnet pool.

name

body

string

Human-readable name of the resource.

default_quota (Optional)

body

integer

A per-project quota on the prefix space that can be allocated from the subnet pool for project subnets. Default is no quota is enforced on allocations from the subnet pool. For IPv4 subnet pools, default_quota is measured in units of /32. For IPv6 subnet pools, default_quota is measured units of /64. All projects that use the subnet pool have the same prefix quota applied.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

prefixes

body

array

A list of subnet prefixes to assign to the subnet pool. The API merges adjacent prefixes and treats them as a single prefix. Each subnet prefix must be unique among all subnet prefixes in all subnet pools that are associated with the address scope.

min_prefixlen (Optional)

body

integer

The smallest prefix that can be allocated from a subnet pool. For IPv4 subnet pools, default is 8. For IPv6 subnet pools, default is 64.

address_scope_id (Optional)

body

object

An address scope to assign to the subnet pool.

ip_version (Optional)

body

integer

The IP protocol version. Valid value is 4 or 6. Default is 4.

shared (Optional)

body

boolean

Indicates whether this resource is shared across all projects. By default, only administrative users can change this value.

default_prefixlen (Optional)

body

integer

The size of the prefix to allocate when the cidr or prefixlen attributes are omitted when you create the subnet. Default is min_prefixlen.

max_prefixlen (Optional)

body

integer

The maximum prefix size that can be allocated from the subnet pool. For IPv4 subnet pools, default is 32. For IPv6 subnet pools, default is 128.

description

body

string

A human-readable description for the resource.

is_default

body

boolean

The subnetpool is default pool or not.

revision_number

body

integer

The revision number of the resource.

tags

body

array

The list of tags on the resource.

Response Example

{
    "subnetpool": {
        "name": "my-new-subnetpool-name",
        "default_quota": null,
        "is_default": false,
        "project_id": "9fadcee8aa7c40cdb2114fff7d569c08",
        "tenant_id": "9fadcee8aa7c40cdb2114fff7d569c08",
        "prefixes": [
            "2001:db8::/63",
            "2001:db8:0:2::/64"
        ],
        "min_prefixlen": 64,
        "address_scope_id": null,
        "ip_version": 6,
        "shared": false,
        "default_prefixlen": 64,
        "id": "03f761e6-eee0-43fc-a921-8acf64c14988",
        "max_prefixlen": 64,
        "description": "",
        "created_at": "2016-03-08T20:19:41",
        "updated_at": "2016-03-08T20:19:41",
        "revision_number": 2,
        "tags": ["tag1,tag2"]
    }
}
DELETE
/v2.0/subnetpools/{subnetpool_id}

Delete subnet pool

Deletes a subnet pool.

The operation fails if any subnets allocated from the subnet pool are still in use.

Normal response codes: 204

Error response codes: 401, 404, 412

Request

Name

In

Type

Description

subnetpool_id

path

string

The UUID of the subnet pool.

Response

There is no body content for the response of a successful DELETE request.

GET
/v2.0/subnetpools

List subnet pools

Lists subnet pools that the project has access to.

Default policy settings return only the subnet pools owned by the project of the user submitting the request, unless the user has administrative role.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

id (Optional)

query

string

Filter the list result by the ID of the resource.

name (Optional)

query

string

Filter the list result by the human-readable name of the resource.

default_quota (Optional)

query

integer

Filter the subnet pool list result by the quota on the prefix space that can be allocated from the subnet pool for project subnets.

tenant_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

project_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

min_prefixlen (Optional)

query

integer

Filter the subnet pool list result by the smallest prefix that can be allocated from a subnet pool.

address_scope_id (Optional)

query

string

Filter the subnet pool list result by the address scope that is assigned to the subnet pool.

ip_version (Optional)

query

integer

Filter the list result by the IP protocol version. Valid value is 4 or 6.

shared (Optional)

query

boolean

Admin-only. Filter the list result based on whether the resource is shared across all projects.

default_prefixlen (Optional)

query

integer

Filter the subnet pool list result by the size of the prefix to allocate when the cidr or prefixlen attributes are omitted when you create the subnet. Default is min_prefixlen.

max_prefixlen (Optional)

query

integer

Filter the subnet pool list result by the maximum prefix size that can be allocated from the subnet pool.

description (Optional)

query

string

Filter the list result by the human-readable description of the resource.

is_default (Optional)

query

boolean

Filter the subnet pool list result based on if it is a default pool or not.

revision_number (Optional)

query

integer

Filter the list result by the revision number of the resource.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a subnetpool attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • address_scope_id

  • default_prefixlen

  • default_quota

  • id

  • ip_version

  • is_default

  • max_prefixlen

  • min_prefixlen

  • name

  • shared

  • tenant_id

  • project_id

tags (Optional)

query

string

A list of tags to filter the list result by. Resources that match all tags in this list will be returned. Tags in query must be separated by comma.

tags-any (Optional)

query

string

A list of tags to filter the list result by. Resources that match any tag in this list will be returned. Tags in query must be separated by comma.

not-tags (Optional)

query

string

A list of tags to filter the list result by. Resources that match all tags in this list will be excluded. Tags in query must be separated by comma.

not-tags-any (Optional)

query

string

A list of tags to filter the list result by. Resources that match any tag in this list will be excluded. Tags in query must be separated by comma.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

subnetpools

body

array

A list of subnetpool objects.

id

body

string

The ID of the subnet pool.

name

body

string

Human-readable name of the resource.

default_quota (Optional)

body

integer

A per-project quota on the prefix space that can be allocated from the subnet pool for project subnets. Default is no quota is enforced on allocations from the subnet pool. For IPv4 subnet pools, default_quota is measured in units of /32. For IPv6 subnet pools, default_quota is measured units of /64. All projects that use the subnet pool have the same prefix quota applied.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

prefixes

body

array

A list of subnet prefixes to assign to the subnet pool. The API merges adjacent prefixes and treats them as a single prefix. Each subnet prefix must be unique among all subnet prefixes in all subnet pools that are associated with the address scope.

min_prefixlen (Optional)

body

integer

The smallest prefix that can be allocated from a subnet pool. For IPv4 subnet pools, default is 8. For IPv6 subnet pools, default is 64.

address_scope_id (Optional)

body

object

An address scope to assign to the subnet pool.

ip_version (Optional)

body

integer

The IP protocol version. Valid value is 4 or 6. Default is 4.

shared (Optional)

body

boolean

Indicates whether this resource is shared across all projects. By default, only administrative users can change this value.

default_prefixlen (Optional)

body

integer

The size of the prefix to allocate when the cidr or prefixlen attributes are omitted when you create the subnet. Default is min_prefixlen.

max_prefixlen (Optional)

body

integer

The maximum prefix size that can be allocated from the subnet pool. For IPv4 subnet pools, default is 32. For IPv6 subnet pools, default is 128.

description

body

string

A human-readable description for the resource.

is_default

body

boolean

The subnetpool is default pool or not.

revision_number

body

integer

The revision number of the resource.

tags

body

array

The list of tags on the resource.

Response Example

{
    "subnetpools": [
        {
            "min_prefixlen": "64",
            "address_scope_id": null,
            "default_prefixlen": "64",
            "id": "03f761e6-eee0-43fc-a921-8acf64c14988",
            "max_prefixlen": "64",
            "name": "my-subnet-pool-ipv6",
            "default_quota": null,
            "is_default": false,
            "project_id": "9fadcee8aa7c40cdb2114fff7d569c08",
            "tenant_id": "9fadcee8aa7c40cdb2114fff7d569c08",
            "prefixes": [
                "2001:db8:0:2::/64",
                "2001:db8::/63"
            ],
            "ip_version": 6,
            "shared": false,
            "description": "",
            "created_at": "2016-03-08T20:19:41",
            "updated_at": "2016-03-08T20:19:41",
            "revision_number": 2,
            "tags": ["tag1,tag2"]
        },
        {
            "min_prefixlen": "24",
            "address_scope_id": null,
            "default_prefixlen": "25",
            "id": "f49a1319-423a-4ee6-ba54-1d95a4f6cc68",
            "max_prefixlen": "30",
            "name": "my-subnet-pool-ipv4",
            "default_quota": null,
            "is_default": false,
            "project_id": "9fadcee8aa7c40cdb2114fff7d569c08",
            "tenant_id": "9fadcee8aa7c40cdb2114fff7d569c08",
            "prefixes": [
                "10.10.0.0/21",
                "192.168.0.0/16"
            ],
            "ip_version": 4,
            "shared": false,
            "description": "",
            "created_at": "2016-03-08T20:19:41",
            "updated_at": "2016-03-08T20:19:41",
            "revision_number": 2,
            "tags": ["tag1,tag2"]
        }
    ]
}
POST
/v2.0/subnetpools

Create subnet pool

Creates a subnet pool.

Normal response codes: 201

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

subnetpool

body

object

A subnetpool object.

name

body

string

Human-readable name of the resource.

default_quota (Optional)

body

integer

A per-project quota on the prefix space that can be allocated from the subnet pool for project subnets. Default is no quota is enforced on allocations from the subnet pool. For IPv4 subnet pools, default_quota is measured in units of /32. For IPv6 subnet pools, default_quota is measured units of /64. All projects that use the subnet pool have the same prefix quota applied.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

prefixes

body

array

A list of subnet prefixes to assign to the subnet pool. The API merges adjacent prefixes and treats them as a single prefix. Each subnet prefix must be unique among all subnet prefixes in all subnet pools that are associated with the address scope.

min_prefixlen (Optional)

body

integer

The smallest prefix that can be allocated from a subnet pool. For IPv4 subnet pools, default is 8. For IPv6 subnet pools, default is 64.

address_scope_id (Optional)

body

object

An address scope to assign to the subnet pool.

shared (Optional)

body

boolean

Indicates whether this resource is shared across all projects. By default, only administrative users can change this value.

default_prefixlen (Optional)

body

integer

The size of the prefix to allocate when the cidr or prefixlen attributes are omitted when you create the subnet. Default is min_prefixlen.

max_prefixlen (Optional)

body

integer

The maximum prefix size that can be allocated from the subnet pool. For IPv4 subnet pools, default is 32. For IPv6 subnet pools, default is 128.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

is_default

body

boolean

The subnetpool is default pool or not.

Request Example

{
    "subnetpool": {
        "name": "my-subnet-pool",
        "prefixes": [
            "192.168.0.0/16",
            "10.10.0.0/21"
        ],
        "default_prefixlen": 25,
        "min_prefixlen": 24,
        "max_prefixlen": 30,
        "shared": "false"
    }
}

Response Parameters

Name

In

Type

Description

subnetpool

body

object

A subnetpool object.

id

body

string

The ID of the subnet pool.

name

body

string

Human-readable name of the resource.

default_quota (Optional)

body

integer

A per-project quota on the prefix space that can be allocated from the subnet pool for project subnets. Default is no quota is enforced on allocations from the subnet pool. For IPv4 subnet pools, default_quota is measured in units of /32. For IPv6 subnet pools, default_quota is measured units of /64. All projects that use the subnet pool have the same prefix quota applied.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

prefixes

body

array

A list of subnet prefixes to assign to the subnet pool. The API merges adjacent prefixes and treats them as a single prefix. Each subnet prefix must be unique among all subnet prefixes in all subnet pools that are associated with the address scope.

min_prefixlen (Optional)

body

integer

The smallest prefix that can be allocated from a subnet pool. For IPv4 subnet pools, default is 8. For IPv6 subnet pools, default is 64.

address_scope_id (Optional)

body

object

An address scope to assign to the subnet pool.

ip_version (Optional)

body

integer

The IP protocol version. Valid value is 4 or 6. Default is 4.

shared (Optional)

body

boolean

Indicates whether this resource is shared across all projects. By default, only administrative users can change this value.

default_prefixlen (Optional)

body

integer

The size of the prefix to allocate when the cidr or prefixlen attributes are omitted when you create the subnet. Default is min_prefixlen.

max_prefixlen (Optional)

body

integer

The maximum prefix size that can be allocated from the subnet pool. For IPv4 subnet pools, default is 32. For IPv6 subnet pools, default is 128.

description

body

string

A human-readable description for the resource.

is_default

body

boolean

The subnetpool is default pool or not.

revision_number

body

integer

The revision number of the resource.

tags

body

array

The list of tags on the resource.

Response Example

{
    "subnetpool": {
        "address_scope_id": null,
        "default_prefixlen": 25,
        "default_quota": null,
        "description": "",
        "id": "f49a1319-423a-4ee6-ba54-1d95a4f6cc68",
        "ip_version": 4,
        "is_default": false,
        "max_prefixlen": 30,
        "min_prefixlen": 24,
        "name": "my-subnet-pool",
        "prefixes": [
            "10.10.0.0/21",
            "192.168.0.0/16"
        ],
        "project_id": "9fadcee8aa7c40cdb2114fff7d569c08",
        "revision_number": 1,
        "shared": false,
        "created_at": "2016-03-08T20:19:41",
        "updated_at": "2016-03-08T20:19:41",
        "tags": ["tag1,tag2"],
        "tenant_id": "9fadcee8aa7c40cdb2114fff7d569c08"
    }
}

Subnet pool prefix operations (subnetpool-prefix-ops)

Add and remove prefixes from a subnet pool prefix list.

PUT
/v2.0/subnetpools/{subnetpool_id}/add_prefixes

Add prefixes

Adds prefixes to a subnet pool.

Normal response codes: 200

Error response codes: 400, 401, 403, 404, 409, 412

Request

Name

In

Type

Description

subnetpool_id

path

string

The UUID of the subnet pool.

prefixes

body

array

A list of subnet prefixes to assign to the subnet pool. The API merges adjacent prefixes and treats them as a single prefix. Each subnet prefix must be unique among all subnet prefixes in all subnet pools that are associated with the address scope.

Request Example

{
  "prefixes": ["192.168.0.0/24", "192.168.1.0/24", "172.16.0.0/21"]
}

Response Parameters

Name

In

Type

Description

prefixes

body

array

A list of the subnet prefixes currently assigned to the subnet pool. Adjacent prefixes are merged and treated as a single prefix.

Response Example

{
  "prefixes": ["192.168.0.0/23", "172.16.0.0/21"]
}
PUT
/v2.0/subnetpools/{subnetpool_id}/remove_prefixes

Remove prefixes

Remove prefixes from a subnet pool.

Normal response codes: 200

Error response codes: 400, 401, 403, 404, 409, 412

Request

Name

In

Type

Description

subnetpool_id

path

string

The UUID of the subnet pool.

prefixes

body

array

A list of subnet prefixes to remove from the subnet pool. The API splits larger prefixes when a subset prefix is removed, and merges any resulting adjacent prefixes to treat them as a single prefix.

Request Example

{
  "prefixes": ["192.168.0.0/24"]
}

Response Parameters

Name

In

Type

Description

prefixes

body

array

A list of the subnet prefixes currently assigned to the subnet pool. Adjacent prefixes are merged and treated as a single prefix.

Response Example

{
  "prefixes": ["192.168.1.0/24", "172.16.0.0/21"]
}

Subnets

Lists, shows details for, creates, updates, and deletes subnet resources.

Default subnetpool extension

The default subnetpool extension (default-subnetpools) allows administrative users to specify default subnetpools (one per IP version). Then users can specify the use_default_subnetpool attribute when creating a subnet, instead of having to specify the subnetpool_id attribute referencing the default subnetpool.

Resource timestamps

The standard-attr-timestamp extension adds the created_at and updated_at attributes to all resources that have standard attributes.

Subnet allocation extension

Subnet allocation extension (subnet_allocation) enables allocation of subnets from a subnet pool.

Subnet DNS publish fixed IP extension

The subnet-dns-publish-fixed-ip extension adds the dns_publish_fixed_ip attribute to subnets. It allows to select per subnet whether DNS records for fixed IPs are to be published in an external DNS service.

Segment extension

The Segments (segment) extension makes it possible to associate a subnet with a specific L2 segment on the network, instead of spanning all the segments in the network. The association between network and subnet remains, but an optional segment_id field is added to the subnet so that it can be associated with a particular segment on the network. With multiple subnets on a network the segment_id is used to determine if the subnets are l2-adjacent or not. Subnets within a network are either all associated to segments, or none of them are associated to segments.

Subnet segment_id writable extension

The subnet segment_id writable (subnet-segmentid-writable) extension enhances the Segments (segment) extension in that now the segment_id attribute is also available for write when a subnet is updated.

Segment peer subnet host routes extension

The segment peer subnet host routes extension ( segments-peer-subnet-host-routes) extension enhances the Segments (segment) extension in that now the host_routes property of the different Subnets (subnets) in a routed network gets routes to the peer subnets on different segments added automatically. This ensures that traffic within an L3 routed network stays within the network even when the default route is on a different host interface.

Subnet service types extension

Subnet service types extension (subnet-service-types) allows administrative users to set the desired port types for a subnet by adding the service_types attributes to subnets. (For example, the network:floatingip_agent_gateway service type enables DVR floating IP agent gateway ports to use the subnet to minimize public IP address consumption).

Tag extension

The standard-attr-tag adds Tag support for resources with standard attributes by adding the tags attribute allowing consumers to associate tags with resources.

GET
/v2.0/subnets

List subnets

Lists subnets that the project has access to.

Default policy settings return only subnets owned by the project of the user submitting the request, unless the user has administrative role. You can control which attributes are returned by using the fields query parameter. You can filter results by using query string parameters.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

id (Optional)

query

string

Filter the list result by the ID of the resource.

tenant_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

project_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

name (Optional)

query

string

Filter the list result by the human-readable name of the resource.

enable_dhcp (Optional)

query

boolean

Filter the subnet list result based on if DHCP is enabled or disabled for the subnet.

network_id (Optional)

query

string

Filter the subnet list result by the ID of the network to which the subnet belongs.

ip_version (Optional)

query

integer

Filter the subnet list result by the IP protocol version. Value is 4 or 6.

gateway_ip (Optional)

query

string

Filter the subnet list result by the gateway IP of this subnet.

cidr (Optional)

query

string

Filter the subnet list result by the CIDR of the subnet.

description (Optional)

query

string

Filter the list result by the human-readable description of the resource.

ipv6_address_mode (Optional)

query

string

Filter the subnet list result by the IPv6 address modes specifies mechanisms for assigning IP addresses. Value is slaac, dhcpv6-stateful, dhcpv6-stateless or null.

ipv6_ra_mode (Optional)

query

string

Filter the subnet list result by the IPv6 router advertisement specifies whether the networking service should transmit ICMPv6 packets for a subnet. Value is slaac, dhcpv6-stateful, dhcpv6-stateless or null.

revision_number (Optional)

query

integer

Filter the list result by the revision number of the resource.

segment_id (Optional)

query

string

Filter the subnet list result by the ID of a network segment the subnet is associated with. It is available when segment extension is enabled.

shared (Optional)

query

boolean

Admin-only. Filter the list result based on whether the resource is shared across all projects.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a subnet attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • cidr

  • enable_dhcp

  • gateway_ip

  • id

  • ip_version

  • ipv6_address_mode

  • ipv6_ra_mode

  • name

  • network_id

  • segment_id

  • subnetpool_id

  • tenant_id

  • project_id

subnetpool_id (Optional)

query

string

Filter the subnet list result by the ID of the subnet pool associated with the subnet.

tags (Optional)

query

string

A list of tags to filter the list result by. Resources that match all tags in this list will be returned. Tags in query must be separated by comma.

tags-any (Optional)

query

string

A list of tags to filter the list result by. Resources that match any tag in this list will be returned. Tags in query must be separated by comma.

not-tags (Optional)

query

string

A list of tags to filter the list result by. Resources that match all tags in this list will be excluded. Tags in query must be separated by comma.

not-tags-any (Optional)

query

string

A list of tags to filter the list result by. Resources that match any tag in this list will be excluded. Tags in query must be separated by comma.

dns_publish_fixed_ip (Optional)

query

boolean

Filter the subnet list result based on if dns_publish_fixed_ip is enabled or disabled for the subnet.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

subnets

body

array

A list of subnet objects.

id

body

string

The ID of the subnet.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

name

body

string

Human-readable name of the resource.

enable_dhcp

body

boolean

Indicates whether dhcp is enabled or disabled for the subnet.

network_id

body

string

The ID of the network to which the subnet belongs.

dns_nameservers

body

array

List of dns name servers associated with the subnet.

allocation_pools

body

array

Allocation pools with start and end IP addresses for this subnet.

host_routes

body

array

Additional routes for the subnet. A list of dictionaries with destination and nexthop parameters.

ip_version

body

integer

The IP protocol version. Value is 4 or 6.

gateway_ip

body

string

Gateway IP of this subnet. If the value is null that implies no gateway is associated with the subnet.

cidr

body

string

The CIDR of the subnet.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

description

body

string

A human-readable description for the resource.

ipv6_address_mode

body

string

The IPv6 address modes specifies mechanisms for assigning IP addresses. Value is slaac, dhcpv6-stateful, dhcpv6-stateless or null.

ipv6_ra_mode

body

string

The IPv6 router advertisement specifies whether the networking service should transmit ICMPv6 packets, for a subnet. Value is slaac, dhcpv6-stateful, dhcpv6-stateless or null.

revision_number

body

integer

The revision number of the resource.

segment_id

body

string

The ID of a network segment the subnet is associated with. It is available when segment extension is enabled.

service_types

body

array

The service types associated with the subnet.

subnetpool_id

body

string

The ID of the subnet pool associated with the subnet.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

tags

body

array

The list of tags on the resource.

dns_publish_fixed_ip

body

boolean

Whether to publish DNS records for IPs from this subnet.

router:external (Optional)

query

boolean

The membership of a subnet to an external network.

Response Example

{
    "subnets": [
        {
            "name": "private-subnet",
            "enable_dhcp": true,
            "network_id": "db193ab3-96e3-4cb3-8fc5-05f4296d0324",
            "segment_id": null,
            "project_id": "26a7980765d0414dbc1fc1f88cdb7e6e",
            "tenant_id": "26a7980765d0414dbc1fc1f88cdb7e6e",
            "dns_nameservers": [],
            "dns_publish_fixed_ip": false,
            "allocation_pools": [
                {
                    "start": "10.0.0.2",
                    "end": "10.0.0.254"
                }
            ],
            "host_routes": [],
            "ip_version": 4,
            "gateway_ip": "10.0.0.1",
            "cidr": "10.0.0.0/24",
            "id": "08eae331-0402-425a-923c-34f7cfe39c1b",
            "created_at": "2016-10-10T14:35:34Z",
            "description": "",
            "ipv6_address_mode": null,
            "ipv6_ra_mode": null,
            "revision_number": 2,
            "service_types": [],
            "subnetpool_id": null,
            "tags": ["tag1,tag2"],
            "updated_at": "2016-10-10T14:35:34Z",
            "router:external": false
        },
        {
            "name": "my_subnet",
            "enable_dhcp": true,
            "network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
            "segment_id": null,
            "project_id": "4fd44f30292945e481c7b8a0c8908869",
            "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
            "dns_nameservers": [],
            "dns_publish_fixed_ip": false,
            "allocation_pools": [
                {
                    "start": "192.0.0.2",
                    "end": "192.255.255.254"
                }
            ],
            "host_routes": [],
            "ip_version": 4,
            "gateway_ip": "192.0.0.1",
            "cidr": "192.0.0.0/8",
            "id": "54d6f61d-db07-451c-9ab3-b9609b6b6f0b",
            "created_at": "2016-10-10T14:35:47Z",
            "description": "",
            "ipv6_address_mode": null,
            "ipv6_ra_mode": null,
            "revision_number": 2,
            "service_types": [],
            "subnetpool_id": null,
            "tags": ["tag1,tag2"],
            "updated_at": "2016-10-10T14:35:47Z",
            "router:external": true
        }
    ]
}
POST
/v2.0/subnets

Create subnet

Creates a subnet on a network.

OpenStack Networking does not try to derive the correct IP version from the CIDR. If you do not specify the gateway_ip attribute, OpenStack Networking allocates an address from the CIDR for the gateway for the subnet.

To specify a subnet without a gateway, set the gateway_ip attribute to null in the request body. If you do not specify the allocation_pools attribute, OpenStack Networking automatically allocates pools for covering all IP addresses in the CIDR, excluding the address reserved for the subnet gateway. Otherwise, you can explicitly specify allocation pools as shown in the following example.

When you specify both the allocation_pools and gateway_ip attributes, you must ensure that the gateway IP does not overlap with the allocation pools; otherwise, the call returns the Conflict (409) response code.

A subnet can have one or more name servers and host routes. Hosts in this subnet use the name servers. Devices with IP addresses from this subnet, not including the local subnet route, use the host routes.

Specify the ipv6_ra_mode and ipv6_address_mode attributes to create subnets that support IPv6 configurations, such as stateless address autoconfiguration (SLAAC), DHCPv6 stateful, and DHCPv6 stateless configurations.

A subnet can optionally be associated with a network segment when it is created by specifying the segment_id of a valid segment on the specified network. A network with subnets associated in this way is called a routed network. On any given network, all of the subnets must be associated with segments or none of them can be. Neutron enforces this invariant. Currently, routed networks are only supported for provider networks.

Note

Creating a subnet does not always result in an automatic port update for the ports which are already bound on the network.

For details see: https://docs.openstack.org/neutron/latest/admin/config-ipv6.html#address-modes-for-ports

Normal response codes: 201

Error response codes: 400, 401, 403, 404, 409

Request

Name

In

Type

Description

subnet

body

object

A subnet object.

tenant_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

project_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

enable_dhcp (Optional)

body

boolean

Indicates whether dhcp is enabled or disabled for the subnet. Default is true.

network_id

body

string

The ID of the network to which the subnet belongs.

dns_nameservers (Optional)

body

array

List of dns name servers associated with the subnet. Default is an empty list.

allocation_pools (Optional)

body

array

Allocation pools with start and end IP addresses for this subnet. If allocation_pools are not specified, OpenStack Networking automatically allocates pools for covering all IP addresses in the CIDR, excluding the address reserved for the subnet gateway by default.

host_routes (Optional)

body

array

Additional routes for the subnet. A list of dictionaries with destination and nexthop parameters. Default value is an empty list.

ip_version

body

integer

The IP protocol version. Value is 4 or 6.

gateway_ip (Optional)

body

string

Gateway IP of this subnet. If the value is null that implies no gateway is associated with the subnet. If the gateway_ip is not specified, OpenStack Networking allocates an address from the CIDR for the gateway for the subnet by default.

cidr

body

string

The CIDR of the subnet.

prefixlen (Optional)

body

integer

The prefix length to use for subnet allocation from a subnet pool. If not specified, the default_prefixlen value of the subnet pool will be used.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

ipv6_address_mode (Optional)

body

string

The IPv6 address modes specifies mechanisms for assigning IP addresses. Value is slaac, dhcpv6-stateful, dhcpv6-stateless.

ipv6_ra_mode (Optional)

body

string

The IPv6 router advertisement specifies whether the networking service should transmit ICMPv6 packets, for a subnet. Value is slaac, dhcpv6-stateful, dhcpv6-stateless.

segment_id (Optional)

body

string

The ID of a network segment the subnet is associated with. It is available when segment extension is enabled.

subnetpool_id (Optional)

body

string

The ID of the subnet pool associated with the subnet.

use_default_subnetpool (Optional)

body

boolean

Whether to allocate this subnet from the default subnet pool.

service_types (Optional)

body

array

The service types associated with the subnet.

dns_publish_fixed_ip (Optional)

body

boolean

Whether to publish DNS records for IPs from this subnet. Default is false.

Request Example

{
    "subnet": {
        "network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
        "ip_version": 4,
        "cidr": "192.168.199.0/24"
    }
}

Response Parameters

Name

In

Type

Description

subnet

body

object

A subnet object.

id

body

string

The ID of the subnet.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

name

body

string

Human-readable name of the resource.

enable_dhcp

body

boolean

Indicates whether dhcp is enabled or disabled for the subnet.

network_id

body

string

The ID of the network to which the subnet belongs.

dns_nameservers

body

array

List of dns name servers associated with the subnet.

allocation_pools

body

array

Allocation pools with start and end IP addresses for this subnet.

host_routes

body

array

Additional routes for the subnet. A list of dictionaries with destination and nexthop parameters.

ip_version

body

integer

The IP protocol version. Value is 4 or 6.

gateway_ip

body

string

Gateway IP of this subnet. If the value is null that implies no gateway is associated with the subnet.

cidr

body

string

The CIDR of the subnet.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

description

body

string

A human-readable description for the resource.

ipv6_address_mode

body

string

The IPv6 address modes specifies mechanisms for assigning IP addresses. Value is slaac, dhcpv6-stateful, dhcpv6-stateless or null.

ipv6_ra_mode

body

string

The IPv6 router advertisement specifies whether the networking service should transmit ICMPv6 packets, for a subnet. Value is slaac, dhcpv6-stateful, dhcpv6-stateless or null.

revision_number

body

integer

The revision number of the resource.

service_types

body

array

The service types associated with the subnet.

subnetpool_id

body

string

The ID of the subnet pool associated with the subnet.

segment_id

body

string

The ID of a network segment the subnet is associated with. It is available when segment extension is enabled.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

tags

body

array

The list of tags on the resource.

dns_publish_fixed_ip

body

boolean

Whether to publish DNS records for IPs from this subnet.

router:external (Optional)

query

boolean

The membership of a subnet to an external network.

Response Example

{
    "subnet": {
        "name": "",
        "enable_dhcp": true,
        "network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
        "segment_id": null,
        "project_id": "4fd44f30292945e481c7b8a0c8908869",
        "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
        "dns_nameservers": [],
        "dns_publish_fixed_ip": false,
        "allocation_pools": [
            {
                "start": "192.168.199.2",
                "end": "192.168.199.254"
            }
        ],
        "host_routes": [],
        "ip_version": 4,
        "gateway_ip": "192.168.199.1",
        "cidr": "192.168.199.0/24",
        "id": "3b80198d-4f7b-4f77-9ef5-774d54e17126",
        "created_at": "2016-10-10T14:35:47Z",
        "description": "",
        "ipv6_address_mode": null,
        "ipv6_ra_mode": null,
        "revision_number": 1,
        "service_types": [],
        "subnetpool_id": null,
        "tags": ["tag1,tag2"],
        "updated_at": "2016-10-10T14:35:47Z",
        "router:external": false
    }
}
POST
/v2.0/subnets

Bulk create subnet

Creates multiple subnets in a single request. Specify a list of subnets in the request body.

The bulk create operation is always atomic. Either all or no subnets in the request body are created.

Normal response codes: 201

Error response codes: 400, 401, 403, 404, 409

Request

Name

In

Type

Description

subnets

body

array

A list of subnet objects.

tenant_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

project_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

enable_dhcp (Optional)

body

boolean

Indicates whether dhcp is enabled or disabled for the subnet. Default is true.

network_id

body

string

The ID of the network to which the subnet belongs.

dns_nameservers (Optional)

body

array

List of dns name servers associated with the subnet. Default is an empty list.

allocation_pools (Optional)

body

array

Allocation pools with start and end IP addresses for this subnet. If allocation_pools are not specified, OpenStack Networking automatically allocates pools for covering all IP addresses in the CIDR, excluding the address reserved for the subnet gateway by default.

host_routes (Optional)

body

array

Additional routes for the subnet. A list of dictionaries with destination and nexthop parameters. Default value is an empty list.

ip_version

body

integer

The IP protocol version. Value is 4 or 6.

gateway_ip (Optional)

body

string

Gateway IP of this subnet. If the value is null that implies no gateway is associated with the subnet. If the gateway_ip is not specified, OpenStack Networking allocates an address from the CIDR for the gateway for the subnet by default.

cidr

body

string

The CIDR of the subnet.

prefixlen (Optional)

body

integer

The prefix length to use for subnet allocation from a subnet pool. If not specified, the default_prefixlen value of the subnet pool will be used.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

ipv6_address_mode (Optional)

body

string

The IPv6 address modes specifies mechanisms for assigning IP addresses. Value is slaac, dhcpv6-stateful, dhcpv6-stateless.

ipv6_ra_mode (Optional)

body

string

The IPv6 router advertisement specifies whether the networking service should transmit ICMPv6 packets, for a subnet. Value is slaac, dhcpv6-stateful, dhcpv6-stateless.

segment_id (Optional)

body

string

The ID of a network segment the subnet is associated with. It is available when segment extension is enabled.

subnetpool_id (Optional)

body

string

The ID of the subnet pool associated with the subnet.

use_default_subnetpool (Optional)

body

boolean

Whether to allocate this subnet from the default subnet pool.

service_types (Optional)

body

array

The service types associated with the subnet.

dns_publish_fixed_ip (Optional)

body

boolean

Whether to publish DNS records for IPs from this subnet. Default is false.

Request Example

{
    "subnets": [
        {
            "cidr": "192.168.199.0/24",
            "ip_version": 4,
            "network_id": "e6031bc2-901a-4c66-82da-f4c32ed89406"
        },
        {
            "cidr": "10.56.4.0/22",
            "ip_version": 4,
            "network_id": "64239a54-dcc4-4b39-920b-b37c2144effa"
        }
    ]
}

Response Parameters

Name

In

Type

Description

subnets

body

array

A list of subnet objects.

id

body

string

The ID of the subnet.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

name

body

string

Human-readable name of the resource.

enable_dhcp

body

boolean

Indicates whether dhcp is enabled or disabled for the subnet.

network_id

body

string

The ID of the network to which the subnet belongs.

dns_nameservers

body

array

List of dns name servers associated with the subnet.

allocation_pools

body

array

Allocation pools with start and end IP addresses for this subnet.

host_routes

body

array

Additional routes for the subnet. A list of dictionaries with destination and nexthop parameters.

ip_version

body

integer

The IP protocol version. Value is 4 or 6.

gateway_ip

body

string

Gateway IP of this subnet. If the value is null that implies no gateway is associated with the subnet.

cidr

body

string

The CIDR of the subnet.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

description

body

string

A human-readable description for the resource.

ipv6_address_mode

body

string

The IPv6 address modes specifies mechanisms for assigning IP addresses. Value is slaac, dhcpv6-stateful, dhcpv6-stateless or null.

ipv6_ra_mode

body

string

The IPv6 router advertisement specifies whether the networking service should transmit ICMPv6 packets, for a subnet. Value is slaac, dhcpv6-stateful, dhcpv6-stateless or null.

revision_number

body

integer

The revision number of the resource.

segment_id

body

string

The ID of a network segment the subnet is associated with. It is available when segment extension is enabled.

service_types

body

array

The service types associated with the subnet.

subnetpool_id

body

string

The ID of the subnet pool associated with the subnet.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

tags

body

array

The list of tags on the resource.

dns_publish_fixed_ip

body

boolean

Whether to publish DNS records for IPs from this subnet.

router:external (Optional)

query

boolean

The membership of a subnet to an external network.

Response Example

{
    "subnets": [
        {
            "allocation_pools": [
                {
                    "end": "192.168.199.254",
                    "start": "192.168.199.2"
                }
            ],
            "cidr": "192.168.199.0/24",
            "dns_nameservers": [],
            "dns_publish_fixed_ip": false,
            "enable_dhcp": true,
            "gateway_ip": "192.168.199.1",
            "host_routes": [],
            "id": "0468a7a7-290d-4127-aedd-6c9449775a24",
            "ip_version": 4,
            "name": "",
            "network_id": "e6031bc2-901a-4c66-82da-f4c32ed89406",
            "segment_id": null,
            "project_id": "d19231fc08ec4bc4829b668040d34512",
            "tenant_id": "d19231fc08ec4bc4829b668040d34512",
            "created_at": "2016-10-10T14:35:47Z",
            "description": "",
            "ipv6_address_mode": null,
            "ipv6_ra_mode": null,
            "revision_number": 1,
            "service_types": [],
            "subnetpool_id": null,
            "tags": ["tag1,tag2"],
            "updated_at": "2016-10-10T14:35:47Z"
        },
        {
            "allocation_pools": [
                {
                    "end": "10.56.7.254",
                    "start": "10.56.4.2"
                }
            ],
            "cidr": "10.56.4.0/22",
            "dns_nameservers": [],
            "dns_publish_fixed_ip": false,
            "enable_dhcp": true,
            "gateway_ip": "10.56.4.1",
            "host_routes": [],
            "id": "b0e7435c-1512-45fb-aa9e-9a7c5932fb30",
            "ip_version": 4,
            "name": "",
            "network_id": "64239a54-dcc4-4b39-920b-b37c2144effa",
            "segment_id": null,
            "project_id": "d19231fc08ec4bc4829b668040d34512",
            "tenant_id": "d19231fc08ec4bc4829b668040d34512",
            "created_at": "2016-10-10T14:35:34Z",
            "description": "",
            "ipv6_address_mode": null,
            "ipv6_ra_mode": null,
            "revision_number": 1,
            "service_types": [],
            "subnetpool_id": null,
            "tags": ["tag1,tag2"],
            "updated_at": "2016-10-10T14:35:34Z"
        }
    ]
}
GET
/v2.0/subnets/{subnet_id}

Show subnet details

Shows details for a subnet.

Use the fields query parameter to filter the results.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

subnet_id

path

string

The ID of the subnet.

Response Parameters

Name

In

Type

Description

subnet

body

object

A subnet object.

id

body

string

The ID of the subnet.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

name

body

string

Human-readable name of the resource.

enable_dhcp

body

boolean

Indicates whether dhcp is enabled or disabled for the subnet.

network_id

body

string

The ID of the network to which the subnet belongs.

dns_nameservers

body

array

List of dns name servers associated with the subnet.

allocation_pools

body

array

Allocation pools with start and end IP addresses for this subnet.

host_routes

body

array

Additional routes for the subnet. A list of dictionaries with destination and nexthop parameters.

ip_version

body

integer

The IP protocol version. Value is 4 or 6.

gateway_ip

body

string

Gateway IP of this subnet. If the value is null that implies no gateway is associated with the subnet.

cidr

body

string

The CIDR of the subnet.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

description

body

string

A human-readable description for the resource.

ipv6_address_mode

body

string

The IPv6 address modes specifies mechanisms for assigning IP addresses. Value is slaac, dhcpv6-stateful, dhcpv6-stateless or null.

ipv6_ra_mode

body

string

The IPv6 router advertisement specifies whether the networking service should transmit ICMPv6 packets, for a subnet. Value is slaac, dhcpv6-stateful, dhcpv6-stateless or null.

revision_number

body

integer

The revision number of the resource.

segment_id

body

string

The ID of a network segment the subnet is associated with. It is available when segment extension is enabled.

service_types

body

array

The service types associated with the subnet.

subnetpool_id

body

string

The ID of the subnet pool associated with the subnet.

tags

body

array

The list of tags on the resource.

dns_publish_fixed_ip

body

boolean

Whether to publish DNS records for IPs from this subnet.

router:external (Optional)

query

boolean

The membership of a subnet to an external network.

Response Example

{
    "subnet": {
        "name": "my_subnet",
        "enable_dhcp": true,
        "network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
        "segment_id": null,
        "project_id": "4fd44f30292945e481c7b8a0c8908869",
        "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
        "created_at": "2016-03-08T20:19:41",
        "dns_nameservers": [],
        "dns_publish_fixed_ip": false,
        "allocation_pools": [
            {
                "start": "192.0.0.2",
                "end": "192.255.255.254"
            }
        ],
        "host_routes": [],
        "ip_version": 4,
        "gateway_ip": "192.0.0.1",
        "cidr": "192.0.0.0/8",
        "updated_at": "2016-03-08T20:19:41",
        "id": "54d6f61d-db07-451c-9ab3-b9609b6b6f0b",
        "description": "",
        "ipv6_address_mode": null,
        "ipv6_ra_mode": null,
        "revision_number": 2,
        "service_types": [],
        "subnetpool_id": null,
        "tags": ["tag1,tag2"],
        "router:external": false
    }
}
PUT
/v2.0/subnets/{subnet_id}

Update subnet

Updates a subnet.

Some attributes, such as IP version (ip_version), CIDR (cidr), and segment (segment_id) cannot be updated. Attempting to update these attributes results in a 400 Bad Request error.

Normal response codes: 200

Error response codes: 400, 401, 403, 404, 412

Request

Name

In

Type

Description

subnet_id

path

string

The ID of the subnet.

name (Optional)

body

string

Human-readable name of the resource.

enable_dhcp (Optional)

body

boolean

Indicates whether dhcp is enabled or disabled for the subnet. Default is true.

dns_nameservers (Optional)

body

array

List of dns name servers associated with the subnet. Default is an empty list.

allocation_pools (Optional)

body

array

Allocation pools with start and end IP addresses for this subnet. If allocation_pools are not specified, OpenStack Networking automatically allocates pools for covering all IP addresses in the CIDR, excluding the address reserved for the subnet gateway by default.

host_routes (Optional)

body

array

Additional routes for the subnet. A list of dictionaries with destination and nexthop parameters. Default value is an empty list.

gateway_ip (Optional)

body

string

Gateway IP of this subnet. If the value is null that implies no gateway is associated with the subnet. If the gateway_ip is not specified, OpenStack Networking allocates an address from the CIDR for the gateway for the subnet by default.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

service_types (Optional)

body

array

The service types associated with the subnet.

segment_id (Optional)

body

string

The ID of a network segment the subnet is associated with. It is available when segment extension is enabled.

dns_publish_fixed_ip (Optional)

body

boolean

Whether to publish DNS records for IPs from this subnet. Default is false.

Request Example

{
    "subnet": {
        "name": "my_subnet"
    }
}

Response Parameters

Name

In

Type

Description

subnet

body

object

A subnet object.

id

body

string

The ID of the subnet.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

name

body

string

Human-readable name of the resource.

enable_dhcp

body

boolean

Indicates whether dhcp is enabled or disabled for the subnet.

network_id

body

string

The ID of the network to which the subnet belongs.

dns_nameservers

body

array

List of dns name servers associated with the subnet.

allocation_pools

body

array

Allocation pools with start and end IP addresses for this subnet.

host_routes

body

array

Additional routes for the subnet. A list of dictionaries with destination and nexthop parameters.

ip_version

body

integer

The IP protocol version. Value is 4 or 6.

gateway_ip

body

string

Gateway IP of this subnet. If the value is null that implies no gateway is associated with the subnet.

cidr

body

string

The CIDR of the subnet.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

description

body

string

A human-readable description for the resource.

ipv6_address_mode

body

string

The IPv6 address modes specifies mechanisms for assigning IP addresses. Value is slaac, dhcpv6-stateful, dhcpv6-stateless or null.

ipv6_ra_mode

body

string

The IPv6 router advertisement specifies whether the networking service should transmit ICMPv6 packets, for a subnet. Value is slaac, dhcpv6-stateful, dhcpv6-stateless or null.

revision_number

body

integer

The revision number of the resource.

segment_id

body

string

The ID of a network segment the subnet is associated with. It is available when segment extension is enabled.

service_types

body

array

The service types associated with the subnet.

subnetpool_id

body

string

The ID of the subnet pool associated with the subnet.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

tags

body

array

The list of tags on the resource.

dns_publish_fixed_ip

body

boolean

Whether to publish DNS records for IPs from this subnet.

router:external (Optional)

query

boolean

The membership of a subnet to an external network.

Response Example

{
    "subnet": {
        "name": "my_subnet",
        "enable_dhcp": true,
        "network_id": "db193ab3-96e3-4cb3-8fc5-05f4296d0324",
        "revision_number": 1,
        "segment_id": null,
        "project_id": "26a7980765d0414dbc1fc1f88cdb7e6e",
        "tenant_id": "26a7980765d0414dbc1fc1f88cdb7e6e",
        "created_at": "2016-03-08T20:19:41",
        "dns_nameservers": [],
        "dns_publish_fixed_ip": false,
        "service_types": [],
        "allocation_pools": [
            {
                "start": "10.0.0.2",
                "end": "10.0.0.254"
            }
        ],
        "host_routes": [],
        "ip_version": 4,
        "gateway_ip": "10.0.0.1",
        "cidr": "10.0.0.0/24",
        "updated_at": "2016-03-08T20:19:41",
        "id": "08eae331-0402-425a-923c-34f7cfe39c1b",
        "description": "",
        "tags": ["tag1,tag2"],
        "router:external": false
    }
}
DELETE
/v2.0/subnets/{subnet_id}

Delete subnet

Deletes a subnet.

The operation fails if subnet IP addresses are still allocated.

Normal response codes: 204

Error response codes: 401, 404, 412

Request

Name

In

Type

Description

subnet_id

path

string

The ID of the subnet.

Response

There is no body content for the response of a successful DELETE request.

Subnet onboard operations (subnet-onboard-ops)

Onboard network subnets into a subnet pool

PUT
/v2.0/subnetpools/{subnetpool_id}/onboard_network_subnets

Onboard subnets

Onboard network subnets to a subnet pool.

Normal response codes: 200

Error response codes: 400

Request

Name

In

Type

Description

network_id

body

string

The ID of the attached network.

subnetpool_id

path

string

The UUID of the subnet pool.

Request Example

{"network_id": "30640c16-a281-4ec5-8ec0-da05a0a5578d"}

Response Parameters

Name

In

Type

Description

subnetpool_id

path

string

The UUID of the subnet pool.

cidr

body

string

The CIDR of the subnet.

Response Example

{
  "subnetpool_id": "5b3d3ffd-109a-4bda-a03c-57b17989b215",
  "cidr": "10.0.2.0/24"
}

Local IPs (local_ips)

Extension that allows users to create a virtual IP that can later be assigned to multiple ports/VMs (similar to anycast IP) and is guaranteed to only be reachable within the same physical server/node boundaries.

Resource timestamps

The standard-attr-timestamp extension adds the created_at and updated_at attributes to all resources that have standard attributes.

GET
/v2.0/local_ips

List Local IPs

Lists Local IPs visible to the user.

Default policy settings return only the Local IPs owned by the user’s project, unless the user has admin role.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

id (Optional)

query

string

Filter the Local IP list result by ID of Local IP

name (Optional)

query

string

Filter the list result by the human-readable name of the resource.

description (Optional)

query

string

Filter the list result by the human-readable description of the resource.

project_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

local_port_id (Optional)

query

string

Filter the Local IP list result by ID of underlying Neutron port

network_id (Optional)

query

string

Filter the list result by the ID of the attached network.

local_ip_address (Optional)

query

string

Filter the Local IP list result by IP address

ip_mode (Optional)

query

string

Filter the Local IP list result by IP mode. Possible values are translate (DNAT) and passthrough (no DNAT)

revision_number (Optional)

query

integer

Filter the list result by the revision number of the resource.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a Local IP attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • id

  • name

  • description

  • project_id

  • local_port_id

  • network_id

  • local_ip_address

  • ip_mode

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

local_ips

body

array

A list of local_ip objects. Each local_ip object represents a Local IP that could be associated with multiple ports

id

body

string

The ID of the Local IP.

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

project_id

body

string

The ID of the project.

local_port_id

body

string

The ID of underlying port of the Local IP.

network_id

body

string

The ID of the attached network.

local_ip_address

body

string

The actual IP address of the Local IP.

ip_mode

body

string

The IP mode of the Local IP. Possible values are translate (DNAT) and passthrough (no DNAT)

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

revision_number

body

integer

The revision number of the resource.

Response Example

{
    "local_ips": [
        {
            "id": "d23abc8d-2991-4a55-ba98-2aaea84cc72f",
            "name": "test_local_ip1",
            "description": "for test",
            "project_id": "4969c491a3c74ee4af974e6d800c62de",
            "local_port_id": "2f245a7b-796b-4f26-9cf9-9e82d248fda7",
            "network_id": "ce705c24-c1ef-408a-bda3-7bbd946164ab",
            "local_ip_address": "100.100.100.100",
            "ip_mode": "translate",
            "created_at": "2021-12-21T10:55:50Z",
            "updated_at": "2021-12-21T10:55:53Z",
            "revision_number": 1
        },
        {
            "id": "61cea855-49cb-4846-997d-801b70c71bdd",
            "name": "test_local_ip2",
            "description": "for test",
            "project_id": "4969c491a3c74ee4af974e6d800c62de",
            "local_port_id": "898b198e-49f7-47d6-a7e1-53f626a548e6",
            "network_id": "376da547-b977-4cfe-9cba-275c80debf57",
            "local_ip_address": "172.24.4.228",
            "ip_mode": "passthrough",
            "created_at": "2021-12-21T20:45:00Z",
            "updated_at": "2021-12-21T20:45:00Z",
            "revision_number": 1
        }
    ]
}
POST
/v2.0/local_ips

Create Local IP

Creates a Local IP, and, if you don’t specify existing port ID, allocates an internal port with IP address from specified network.

The operation returns the Bad Request (400) response code for one of reasons:

  • The requested local IP address does not fall in the subnet range for the specified network.

  • The local IP address is not valid.

  • Specified local_port_id has no fixed IP address

  • Specified local_port_id has multiple fixed IP address and local_ip was not specified

  • Specified ip_mode is not supported

If the local_port_id or network_id is not valid, this operation returns 404 response code.

The operation returns the Conflict (409) response code for one of reasons:

  • Both local_port_id and network_id are specified in the request

  • Both local_port_id and local_ip are specified, but port has no such local IP

  • Both network_id and local_ip_address are specified, but network has no subnets to satisfy the IP requested

Normal response codes: 201

Error response codes: 400, 401, 404, 409

Request

Name

In

Type

Description

local_ip

body

object

A local_ip object represents a Local IP that could be associated with multiple ports

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

project_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

local_port_ip

body

string

The requested ID of the underlying port of the Local IP

network_id

body

string

The requested ID of the network of the Local IP

local_ip_address (Optional)

body

string

The requested actual IP address of the Local IP.

ip_mode (Optional)

body

string

The requested IP mode of the Local IP. Possible values are translate (DNAT) and passthrough (no DNAT)

Request Example

{
    "local_ip": {
        "name": "test_local_ip",
        "description": "local ip for testing",
        "network_id": "ce705c24-c1ef-408a-bda3-7bbd946164ab",
        "local_ip_address": "172.24.4.228",
        "ip_mode": "translate"
    }
}

Response Parameters

Name

In

Type

Description

local_ip

body

object

A local_ip object represents a Local IP that could be associated with multiple ports

id

body

string

The ID of the Local IP.

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

project_id

body

string

The ID of the project.

local_port_id

body

string

The ID of underlying port of the Local IP.

network_id

body

string

The ID of the network of the Local IP.

local_ip_address

body

string

The actual IP address of the Local IP.

ip_mode

body

string

The IP mode of the Local IP. Possible values are translate (DNAT) and passthrough (no DNAT)

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

revision_number

body

integer

The revision number of the resource.

Response Example

{
    "local_ip": {
        "id": "d23abc8d-2991-4a55-ba98-2aaea84cc72f",
        "name": "test_local_ip",
        "description": "local ip for testing",
        "project_id": "4969c491a3c74ee4af974e6d800c62de",
        "local_port_id": "2f245a7b-796b-4f26-9cf9-9e82d248fda7",
        "network_id": "ce705c24-c1ef-408a-bda3-7bbd946164ab",
        "local_ip_address": "172.24.4.228",
        "ip_mode": "translate",
        "created_at": "2021-12-21T10:55:50Z",
        "updated_at": "2021-12-21T10:55:53Z",
        "revision_number": 1
    }
}
GET
/v2.0/local_ips/{local_ip_id}

Show Local IP details

Shows details for a Local IP.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 403, 404

Request

Name

In

Type

Description

local_ip_id

path

string

The ID of the Local IP

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

local_ip

body

object

A local_ip object represents a Local IP that could be associated with multiple ports

id

body

string

The ID of the Local IP.

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

project_id

body

string

The ID of the project.

local_port_id

body

string

The ID of underlying port of the Local IP.

network_id

body

string

The ID of the network of the Local IP.

local_ip_address

body

string

The actual IP address of the Local IP.

ip_mode

body

string

The IP mode of the Local IP. Possible values are translate (DNAT) and passthrough (no DNAT)

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

revision_number

body

integer

The revision number of the resource.

Response Example

{
    "local_ip": {
        "id": "d23abc8d-2991-4a55-ba98-2aaea84cc72f",
        "name": "test_local_ip",
        "description": "local ip for testing",
        "project_id": "4969c491a3c74ee4af974e6d800c62de",
        "local_port_id": "2f245a7b-796b-4f26-9cf9-9e82d248fda7",
        "network_id": "ce705c24-c1ef-408a-bda3-7bbd946164ab",
        "local_ip_address": "172.24.4.228",
        "ip_mode": "translate",
        "created_at": "2021-12-21T10:55:50Z",
        "updated_at": "2021-12-21T10:55:53Z",
        "revision_number": 1
    }
}
PUT
/v2.0/local_ips/{local_ip_id}

Update Local IP

Updates a Local IP.

Normal response codes: 200

Error response codes: 400, 401, 404, 409

Request

Name

In

Type

Description

local_ip

body

object

A local_ip object represents a Local IP that could be associated with multiple ports

local_ip_id

path

string

The ID of the Local IP

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

Request Example

{
    "local_ip": {
        "name": "new_name",
        "description": "new description"
    }
}

Response Parameters

Name

In

Type

Description

local_ip

body

object

A local_ip object represents a Local IP that could be associated with multiple ports

id

body

string

The ID of the Local IP.

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

project_id

body

string

The ID of the project.

local_port_id

body

string

The ID of underlying port of the Local IP.

network_id

body

string

The ID of the network of the Local IP.

local_ip_address

body

string

The actual IP address of the Local IP.

ip_mode

body

string

The IP mode of the Local IP. Possible values are translate (DNAT) and passthrough (no DNAT)

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

revision_number

body

integer

The revision number of the resource.

Response Example

{
    "local_ip": {
        "id": "d23abc8d-2991-4a55-ba98-2aaea84cc72f",
        "name": "new_name",
        "description": "now in passthrough mode",
        "project_id": "4969c491a3c74ee4af974e6d800c62de",
        "local_port_id": "2f245a7b-796b-4f26-9cf9-9e82d248fda7",
        "network_id": "ce705c24-c1ef-408a-bda3-7bbd946164ab",
        "local_ip_address": "172.24.4.228",
        "ip_mode": "passthrough",
        "created_at": "2021-12-21T10:55:50Z",
        "updated_at": "2021-12-21T10:55:53Z",
        "revision_number": 1
    }
}
DELETE
/v2.0/local_ips/{local_ip_id}

Delete Local IP

Deletes a Local IP and, if applicable, its underlying port. Underlying port is deleted in case it was created specifically for this Local IP, and has corresponding device_owner and device_id.

The operation returns the Precondition Failed  (412) response code for the following reason:

  • The requested Local IP is still associated with some ports.

Normal response codes: 204

Error response codes: 401, 404, 412

Request

Name

In

Type

Description

local_ip_id

path

string

The ID of the Local IP

Response

There is no body content for the response of a successful DELETE request.

Local IP Associations (port_associations)

The resource lets users assign Local IPs to user Ports. This is a sub-resource of the Local IP resource.

GET
/v2.0/local_ips/{local_ip_id}/port_associations

List Local IP Associations

Lists Associations for the given Local IP.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

local_ip_id

path

string

The ID of the Local IP

fixed_port_id (Optional)

query

string

Filter the Local IP Association list result by ID of associated ports

fixed_ip (Optional)

query

string

Filter the Local IP Association list result by IP of associated ports

host (Optional)

query

string

Filter the Local IP Association list result by host of associated ports

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a Local IP Association attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • local_ip_id

  • fixed_port_id

  • fixed_ip

  • host

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

local_ip_associations

body

array

A list of local_ip_association objects. Each local_ip_association object represents a Local IP Association with a port

local_ip_id

body

string

The ID of the Local IP.

local_ip_address

body

string

The actual IP address of the Local IP.

fixed_port_id

body

string

The ID of the port associated with the Local IP.

fixed_ip (Optional)

body

string

The IP of the port associated with the Local IP.

host (Optional)

body

string

The host of the port associated with the Local IP.

Response Example

{
  "port_associations": [
    {
      "local_ip_id": "8c5d88dc-60ac-4b02-a65a-36b65888ddcd",
      "local_ip_address": "172.24.4.228",
      "fixed_port_id": "96227c78-6a0c-4d9d-b441-c4b8f6fb6c4a",
      "fixed_ip": "10.0.0.5",
      "host": "host1"
    },
    {
      "local_ip_id": "8c5d88dc-60ac-4b02-a65a-36b65888ddcd",
      "local_ip_address": "172.24.4.228",
      "fixed_port_id": "1b09fd12-c769-4be7-9c26-dececa474acf",
      "fixed_ip": "10.0.0.6",
      "host": "host2"
    }
  ]
}
POST
/v2.0/local_ips/{local_ip_id}/port_associations

Create Local IP Association

Creates a Local IP association with a given Port. If a Port has multiple fixed IPs user must specify which IP to use for association.

The operation returns the Conflict (409) response code for one of reasons:

  • Specified fixed_port_id has multiple fixed IP addresses and fixed_ip was not specified

  • Both fixed_port_id and fixed_ip are specified in the request, but port has no such fixed IP

Normal response codes: 201

Error response codes: 400, 401, 404, 409

Request

Name

In

Type

Description

local_ip_id

path

string

The ID of the Local IP

fixed_port_id

body

string

The requested ID of the port associated with the Local IP.

fixed_ip (Optional)

body

string

The requested IP of the port associated with the Local IP.

Request Example

{
  "port_association": {
    "fixed_port_id": "96227c78-6a0c-4d9d-b441-c4b8f6fb6c4a",
    "fixed_ip": "10.0.0.5"
  }
}

Response Parameters

Name

In

Type

Description

local_ip_association

body

object

A local_ip_association object represents a Local IP Association with a port

local_ip_id

body

string

The ID of the associated Local IP.

fixed_port_id

body

string

The ID of the port associated with the Local IP.

fixed_ip (Optional)

body

string

The IP of the port associated with the Local IP.

host (Optional)

body

string

The host of the port associated with the Local IP.

Response Example

{
  "port_association": {
      "local_ip_id": "8c5d88dc-60ac-4b02-a65a-36b65888ddcd",
      "local_ip_address": "172.24.4.228",
      "fixed_port_id": "96227c78-6a0c-4d9d-b441-c4b8f6fb6c4a",
      "fixed_ip": "10.0.0.5",
      "host": "host1"
  }
}
DELETE
/v2.0/local_ips/{local_ip_id}/port_associations/{fixed_port_id}

Delete Local IP Association

Deletes a Local IP association.

Normal response codes: 204

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

local_ip_id

path

string

The ID of the Local IP

fixed_port_id

path

string

The ID of the port associated with the Local IP.

Response

There is no body content for the response of a successful DELETE request.

Security

Address groups

Lists, creates, shows details for, updates, and deletes address groups.

GET
/v2.0/address-groups/{address_group_id}

Show address group

Shows information for an address group.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

address_group_id

path

string

The ID of the address group.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

address_group

body

object

An address group object.

id

body

string

The ID of the address group.

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

addresses

body

array

A list of IP addresses.

Response Example

{
  "addresses": [
    "10.0.1.34/32",
    "192.168.100.0/24"
  ],
  "description": "",
  "id": "9ace2ef6-bd57-426a-9223-cf1751d26db9",
  "name": "doc-address-group",
  "project_id": "c9a6f447205640e89523df967c26f4d5"
}
PUT
/v2.0/address-groups/{address_group_id}

Update an address group

Updates an address group.

Normal response codes: 200

Error response codes: 400, 401, 403, 404, 412

Request

Name

In

Type

Description

address_group_id

path

string

The ID of the address group.

address_group

body

object

An address group object.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

description

body

string

A human-readable description for the resource.

Request Example

{
    "address_group": {
        "description": "AG description"
    }
}

Response Parameters

Name

In

Type

Description

address_group

body

object

An address group object.

id

body

string

The ID of the address group.

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

addresses

body

array

A list of IP addresses.

Response Example

{
    "address_group": {
        "id": "9ace2ef6-bd57-426a-9223-cf1751d26db9",
        "name": "doc-address-group",
        "project_id": "c9a6f447205640e89523df967c26f4d5",
        "addresses": [
            "10.0.1.34/32",
            "10.0.2.100/32",
            "192.168.100.0/24"
        ],
        "description": "AG description",
        "tenant_id": "c9a6f447205640e89523df967c26f4d5"
    }
}
DELETE
/v2.0/address-groups/{address_group_id}

Delete an address group

Deletes an address group.

Normal response codes: 204

Error response codes: 401, 404, 412

Request

Name

In

Type

Description

address_group_id

path

string

The ID of the address group.

Response

There is no body content for the response of a successful DELETE request.

GET
/v2.0/address-groups

List address groups

Lists address groups that the project has access to.

Default policy settings return only the address groups owned by the project of the user submitting the request, unless the user has administrative role.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

id (Optional)

query

string

Filter the list result by the ID of the resource.

name (Optional)

query

string

Filter the list result by the human-readable name of the resource.

tenant_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

project_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

sort_key (Optional)

query

string

Sorts by an address group attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • id

  • name

  • project_id

  • shared

  • tenant_id

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

address_groups

body

array

A list of address group objects.

id

body

string

The ID of the address group.

name

body

string

Human-readable name of the resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

addresses

body

array

A list of IP addresses.

Response Example

{
    "address_groups": [
        {
            "id": "9ace2ef6-bd57-426a-9223-cf1751d26db9",
            "name": "doc-address-group",
            "project_id": "c9a6f447205640e89523df967c26f4d5",
            "addresses": [
                "10.0.1.34/32",
                "10.0.2.100/32",
                "192.168.100.0/24"
            ],
            "description": "",
            "tenant_id": "c9a6f447205640e89523df967c26f4d5"
        }
    ]
}
POST
/v2.0/address-groups

Create address group

Creates an address group.

Normal response codes: 201

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

address_group_id

path

string

The ID of the address group.

address_group

body

object

An address group object.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

description

body

string

A human-readable description for the resource.

addresses

body

array

A list of IP addresses.

Request Example

{
    "address_group": {
        "addresses": [],
        "name": "address-group-2",
        "description": "docs example group"
    }
}

Response Parameters

Name

In

Type

Description

address_group

body

object

An address group object.

id

body

string

The ID of the address group.

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

addresses

body

array

A list of IP addresses.

Response Example

{
    "address_group": {
        "id": "9f60873a-9bb0-45c9-ac25-b1d5d668d955",
        "name": "address-group-2",
        "project_id": "c9a6f447205640e89523df967c26f4d5",
        "addresses": [],
        "description": "docs example group",
        "tenant_id": "c9a6f447205640e89523df967c26f4d5"
    }
}
PUT
/v2.0/address-group/{address_group_id}/add_addresses

Add IP addresses to address group

Atomically adds a set of IP addresses to the address group’s already existing addresses.

Normal response codes: 200

Error response codes: 400, 401, 404, 412

Request

Name

In

Type

Description

address_group_id

path

string

The ID of the address group.

addresses

body

array

A list of IP addresses.

Request Example

{
    "address_group": {
        "addresses": ["10.0.2.100/32"]
    }
}

Response Parameters

Name

In

Type

Description

address_group

body

object

An address group object.

id

body

string

The ID of the address group.

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

addresses

body

array

A list of IP addresses.

Response Example

{
    "address_group": {
        "id": "9ace2ef6-bd57-426a-9223-cf1751d26db9",
        "name": "doc-address-group",
        "project_id": "c9a6f447205640e89523df967c26f4d5",
        "addresses": [
            "10.0.1.34/32",
            "10.0.2.100/32",
            "192.168.100.0/24"
        ],
        "description": "AG description",
        "tenant_id": "c9a6f447205640e89523df967c26f4d5"
    }
}
PUT
/v2.0/address-group/{address_group_id}/remove_addresses

Remove IP addresses to address group

Atomically removes a set of IP addresses from the address group’s already existing addresses.

Normal response codes: 200

Error response codes: 400, 401, 404, 412

Request

Name

In

Type

Description

address_group_id

path

string

The ID of the address group.

addresses

body

array

A list of IP addresses.

Request Example

{
    "address_group": {
        "addresses": ["10.0.2.100/32"]
    }
}

Response Parameters

Name

In

Type

Description

address_group

body

object

An address group object.

id

body

string

The ID of the address group.

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

addresses

body

array

A list of IP addresses.

Response Example

{
    "address_group": {
        "id": "9ace2ef6-bd57-426a-9223-cf1751d26db9",
        "name": "doc-address-group",
        "project_id": "c9a6f447205640e89523df967c26f4d5",
        "addresses": [
            "10.0.1.34/32",
            "192.168.100.0/24"
        ],
        "description": "AG description",
        "tenant_id": "c9a6f447205640e89523df967c26f4d5"
    }
}

FWaaS v2.0 (CURRENT) (fwaas, firewall_groups, firewall_policies, firewall_rules)

Use the Firewall-as-a-Service (FWaaS) v2.0 extension to deploy firewall groups to protect your networks.

The FWaaS extension enables you to:

  • Apply firewall rules on traffic entering and leaving project networks.

  • Apply TCP, UDP, ICMP, or protocol-agnostic rules.

  • Create and share firewall policies that hold an ordered collection of firewall rules.

  • Audit firewall rules and policies.

This extension introduces the following resources:

  • firewall_group. A logical firewall resource that a project can create and manage. A firewall group can have a firewall policy for ingress traffic and/or a firewall policy for egress traffic.

  • firewall_policy. An ordered collection of firewall rules. You can share a firewall policy across projects. You can include a firewall policy as part of an audit workflow so that an authorized relevant entity can audit the firewall policy. This entity can differ from the user who created, or the projects that use, the firewall policy.

  • firewall_rule. A collection of attributes, such as source and destination ports, source and destination IP addresses, protocol, and IP version. These attributes define match criteria and an action to take, such as allow, reject, or deny, on matched data traffic.

GET
/v2.0/fwaas/firewall_groups

List firewall groups

Lists all firewall groups.

The list might be empty.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401, 403

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

firewall_groups

body

array

A list of firewall_group objects.

admin_state_up

body

boolean

The administrative state of the firewall group, which is up (true) or down (false). Default is true.

description

body

object

A human-readable description of the firewall group.

egress_firewall_policy_id

body

string

The ID of the egress firewall policy for the firewall group.

id

body

string

The ID of the firewall group.

ingress_firewall_policy_id

body

string

The ID of the ingress firewall policy for the firewall group.

name

body

string

A human-readable name for the firewall group.

ports

body

array

A list of the IDs of the ports associated with the firewall group.

project_id

body

string

The ID of the project that owns the resource.

shared

body

boolean

Indicates whether this firewall group is shared across all projects.

status

body

string

The status of the firewall group. Valid values are ACTIVE, INACTIVE, ERROR, PENDING_UPDATE, or PENDING_DELETE.

tenant_id

body

string

The ID of the project that owns the resource.

Response Example

{
    "firewall_groups": [
        {
            "admin_state_up": true,
            "description": "",
            "egress_firewall_policy_id": "c69933c1-b472-44f9-8226-30dc4ffd454c",
            "id": "3b0ef8f4-82c7-44d4-a4fb-6177f9a21977",
            "ingress_firewall_policy_id": "c69933c1-b472-44f9-8226-30dc4ffd454c",
            "name": "",
            "ports": [
                "650bfd2f-7766-4a0d-839f-218f33e16998"
            ],
            "shared": true,
            "project_id": "45977fa2dbd7482098dd68d0d8970117",
            "status": "ACTIVE",
            "tenant_id": "45977fa2dbd7482098dd68d0d8970117"
        }
    ]
}
GET
/v2.0/fwaas/firewall_groups/{firewall_group_id}

Show firewall group details

Shows details for a firewall group.

If the user is not an administrative user and the firewall group object does not belong to the project, this call returns the FirewallGroupNotFound (404) response code.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 403, 404

Request

Name

In

Type

Description

firewall_group_id

path

string

The ID of the firewall group.

Response Parameters

Name

In

Type

Description

firewall_group

body

object

A firewall_group object.

admin_state_up

body

boolean

The administrative state of the firewall group, which is up (true) or down (false). Default is true.

description

body

object

A human-readable description of the firewall group.

egress_firewall_policy_id

body

string

The ID of the egress firewall policy for the firewall group.

id

body

string

The ID of the firewall group.

ingress_firewall_policy_id

body

string

The ID of the ingress firewall policy for the firewall group.

name

body

string

A human-readable name for the firewall group.

ports

body

array

A list of the IDs of the ports associated with the firewall group.

project_id

body

string

The ID of the project that owns the resource.

shared

body

boolean

Indicates whether this firewall group is shared across all projects.

status

body

string

The status of the firewall group. Valid values are ACTIVE, INACTIVE, ERROR, PENDING_UPDATE, or PENDING_DELETE.

tenant_id

body

string

The ID of the project that owns the resource.

Response Example

{
    "firewall_group": {
        "admin_state_up": true,
        "description": "",
        "egress_firewall_policy_id": null,
        "id": "07411bda-0147-418b-af05-c8665630d937",
        "ingress_firewall_policy_id": null,
        "name": "",
        "project_id": "96108b04417b416e9b9bc788c11c42c9",
        "shared": false,
        "status": "INACTIVE",
        "tenant_id": "96108b04417b416e9b9bc788c11c42c9"
    }
}
POST
/v2.0/fwaas/firewall_groups

Create firewall group

Creates a firewall group.

The firewall group may be associated with an ingress firewall policy and/or an egress firewall policy.

If admin_state_up is false, the firewall group will block all traffic.

Normal response codes: 201

Error response codes: 400, 401

Request

Name

In

Type

Description

firewall_group

body

object

A firewall_group object.

admin_state_up (Optional)

body

boolean

The administrative state of the firewall group, which is up (true) or down (false). Default is true.

description (Optional)

body

object

A human-readable description of the firewall group.

egress_firewall_policy_id (Optional)

body

string

The ID of the egress firewall policy for the firewall group.

ingress_firewall_policy_id (Optional)

body

string

The ID of the ingress firewall policy for the firewall group.

name (Optional)

body

string

A human-readable name for the firewall group.

ports (Optional)

body

array

A list of the IDs of the ports associated with the firewall group.

project_id (Optional)

body

string

The ID of the project that owns the resource.

shared (Optional)

body

boolean

Indicates whether this firewall group is shared across all projects.

tenant_id (Optional)

body

string

The ID of the project that owns the resource.

Request Example

{
    "firewall_group": {
        "admin_state_up": false,
        "egress_firewall_policy_id": "14c9d3c1-b472-44f9-8226-30dc4ffd454c",
        "ingress_firewall_policy_id": "c69933c1-b472-44f9-8226-30dc4ffd454c"
    }
}

Response Parameters

Name

In

Type

Description

firewall_group

body

object

A firewall_group object.

admin_state_up

body

boolean

The administrative state of the firewall group, which is up (true) or down (false). Default is true.

description

body

object

A human-readable description of the firewall group.

egress_firewall_policy_id

body

string

The ID of the egress firewall policy for the firewall group.

id

body

string

The ID of the firewall group.

ingress_firewall_policy_id

body

string

The ID of the ingress firewall policy for the firewall group.

name

body

string

A human-readable name for the firewall group.

ports

body

array

A list of the IDs of the ports associated with the firewall group.

project_id

body

string

The ID of the project that owns the resource.

shared

body

boolean

Indicates whether this firewall group is shared across all projects.

status

body

string

The status of the firewall group. Valid values are ACTIVE, INACTIVE, ERROR, PENDING_UPDATE, or PENDING_DELETE.

tenant_id

body

string

The ID of the project that owns the resource.

Response Example

{
    "firewall_group": {
        "admin_state_up": true,
        "description": "",
        "egress_firewall_policy_id": "1244ed87-b472-44f9-8226-30dc4ffd454c",
        "ingress_firewall_policy_id": "c69933c1-b472-44f9-8226-30dc4ffd454c",
        "id": "3b0ef8f4-82c7-44d4-a4fb-6177f9a21977",
        "name": "",
        "ports": [
            "650bfd2f-7766-4a0d-839f-218f33e16998"
        ],
        "project_id": "45977fa2dbd7482098dd68d0d8970117",
        "shared": true,
        "status": "PENDING_CREATE",
        "tenant_id": "45977fa2dbd7482098dd68d0d8970117"
    }
}
PUT
/v2.0/fwaas/firewall_groups/{firewall_group_id}

Update firewall group

Updates a firewall group.

The firewall group cannot be updated if its status is a PENDING_* status.

Normal response codes: 200

Error response codes: 400, 401, 404

Request

Name

In

Type

Description

firewall_group_id

path

string

The ID of the firewall group.

firewall_group

body

object

A firewall_group object.

admin_state_up (Optional)

body

boolean

The administrative state of the firewall group, which is up (true) or down (false). Default is true.

description (Optional)

body

object

A human-readable description of the firewall group.

egress_firewall_policy_id (Optional)

body

string

The ID of the egress firewall policy for the firewall group.

ingress_firewall_policy_id (Optional)

body

string

The ID of the ingress firewall policy for the firewall group.

name (Optional)

body

string

A human-readable name for the firewall group.

ports (Optional)

body

array

A list of the IDs of the ports associated with the firewall group.

shared (Optional)

body

boolean

Indicates whether this firewall group is shared across all projects.

Request Example

{
    "firewall_group": {
        "admin_state_up": "false"
    }
}

Response Parameters

Name

In

Type

Description

firewall_group

body

object

A firewall_group object.

admin_state_up

body

boolean

The administrative state of the firewall group, which is up (true) or down (false). Default is true.

description

body

object

A human-readable description of the firewall group.

egress_firewall_policy_id

body

string

The ID of the egress firewall policy for the firewall group.

id

body

string

The ID of the firewall group.

ingress_firewall_policy_id

body

string

The ID of the ingress firewall policy for the firewall group.

name

body

string

A human-readable name for the firewall group.

ports

body

array

A list of the IDs of the ports associated with the firewall group.

project_id

body

string

The ID of the project that owns the resource.

shared

body

boolean

Indicates whether this firewall group is shared across all projects.

status

body

string

The status of the firewall group. Valid values are ACTIVE, INACTIVE, ERROR, PENDING_UPDATE, or PENDING_DELETE.

tenant_id

body

string

The ID of the project that owns the resource.

Response Example

{
    "firewall_group": {
        "admin_state_up": false,
        "description": "",
        "egress_firewall_policy_id": "c69933c1-b472-44f9-8226-30dc4ffd454c",
        "ingress_firewall_policy_id": "c69933c1-b472-44f9-8226-30dc4ffd454c",
        "id": "3b0ef8f4-82c7-44d4-a4fb-6177f9a21977",
        "name": "",
        "ports": [
            "650bfd2f-7766-4a0d-839f-218f33e16998"
        ],
        "shared": true,
        "project_id": "45977fa2dbd7482098dd68d0d8970117",
        "status": "PENDING_UPDATE",
        "tenant_id": "45977fa2dbd7482098dd68d0d8970117"
    }
}
DELETE
/v2.0/fwaas/firewall_groups/{firewall_group_id}

Delete firewall group

Deletes a firewall group.

Normal response codes: 204

Error response codes: 401, 404, 409

Request

Name

In

Type

Description

firewall_group_id

path

string

The ID of the firewall group.

Response

There is no body content for the response of a successful DELETE request.

GET
/v2.0/fwaas/firewall_policies

List firewall policies

Lists all firewall policies.

The list might be empty.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401, 403

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

firewall_policies

body

array

A list of firewall_policy objects.

audited

body

boolean

Each time that the firewall policy or its associated rules are changed, the API sets this attribute to false. To audit the policy, explicitly set this attribute to true.

description

body

string

A human-readable name of the firewall policy.

id

body

string

The ID of the firewall policy.

firewall_rules

body

array

A list of the IDs of the firewall rules associated with the firewall policy.

name

body

string

A human-readable name of the firewall policy.

project_id

body

string

The ID of the project that owns the resource.

shared

body

boolean

Set to true to make this firewall policy visible to other projects. Default is false.

tenant_id

body

string

The ID of the project that owns the resource.

Response Example

{
    "firewall_policies": [
        {
            "audited": false,
            "description": "",
            "firewall_rules": [
                "8722e0e0-9cc9-4490-9660-8c9a5732fbb0"
            ],
            "id": "c69933c1-b472-44f9-8226-30dc4ffd454c",
            "name": "test-policy",
            "project_id": "45977fa2dbd7482098dd68d0d8970117",
            "shared": false,
            "tenant_id": "45977fa2dbd7482098dd68d0d8970117"
        }
    ]
}
GET
/v2.0/fwaas/firewall_policies/{firewall_policy_id}

Show firewall policy details

Shows details of a firewall policy.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 403, 404

Request

Name

In

Type

Description

firewall_policy_id

path

string

The ID of the firewall policy.

Response Parameters

Name

In

Type

Description

audited

body

boolean

Each time that the firewall policy or its associated rules are changed, the API sets this attribute to false. To audit the policy, explicitly set this attribute to true.

description

body

string

A human-readable name of the firewall policy.

firewall_rules

body

array

A list of the IDs of the firewall rules associated with the firewall policy.

id

body

string

The ID of the firewall policy.

name

body

string

A human-readable name of the firewall policy.

project_id

body

string

The ID of the project that owns the resource.

shared

body

boolean

Set to true to make this firewall policy visible to other projects. Default is false.

tenant_id

body

string

The ID of the project that owns the resource.

Response Example

{
    "firewall_policy": {
        "audited": false,
        "description": "",
        "firewall_rules": [
            "8722e0e0-9cc9-4490-9660-8c9a5732fbb0"
        ],
        "id": "c69933c1-b472-44f9-8226-30dc4ffd454c",
        "name": "test-policy",
        "project_id": "45977fa2dbd7482098dd68d0d8970117",
        "shared": false,
        "tenant_id": "45977fa2dbd7482098dd68d0d8970117"
    }
}
POST
/v2.0/fwaas/firewall_policies

Create firewall policy

Creates a firewall policy.

Normal response codes: 201

Error response codes: 400, 401

Request

Name

In

Type

Description

firewall_policy

body

object

A firewall_policy object.

audited (Optional)

body

boolean

Each time that the firewall policy or its associated rules are changed, the API sets this attribute to false. To audit the policy, explicitly set this attribute to true.

description (Optional)

body

string

A human-readable name of the firewall policy.

firewall_rules (Optional)

body

array

A list of the IDs of the firewall rules associated with the firewall policy.

name (Optional)

body

string

A human-readable name of the firewall policy.

project_id (Optional)

body

string

The ID of the project that owns the resource.

shared (Optional)

body

boolean

Set to true to make this firewall policy visible to other projects. Default is false.

tenant_id (Optional)

body

string

The ID of the project that owns the resource.

Request Example

{
    "firewall_policy": {
        "name": "test-policy",
        "firewall_rules": [
            "8722e0e0-9cc9-4490-9660-8c9a5732fbb0"
        ]
    }
}

Response Parameters

Name

In

Type

Description

firewall_policy

body

object

A firewall_policy object.

audited

body

boolean

Each time that the firewall policy or its associated rules are changed, the API sets this attribute to false. To audit the policy, explicitly set this attribute to true.

description

body

string

A human-readable name of the firewall policy.

firewall_rules

body

array

A list of the IDs of the firewall rules associated with the firewall policy.

id

body

string

The ID of the firewall policy.

name

body

string

A human-readable name of the firewall policy.

project_id

body

string

The ID of the project that owns the resource.

shared

body

boolean

Set to true to make this firewall policy visible to other projects. Default is false.

tenant_id

body

string

The ID of the project that owns the resource.

Response Example

{
    "firewall_policy": {
        "audited": false,
        "description": "",
        "firewall_rules": [
            "8722e0e0-9cc9-4490-9660-8c9a5732fbb0"
        ],
        "id": "c69933c1-b472-44f9-8226-30dc4ffd454c",
        "name": "test-policy",
        "project_id": "45977fa2dbd7482098dd68d0d8970117",
        "shared": false,
        "tenant_id": "45977fa2dbd7482098dd68d0d8970117"
    }
}
PUT
/v2.0/fwaas/firewall_policies/{firewall_policy_id}

Update firewall policy

Updates a firewall policy.

Normal response codes: 200

Error response codes: 400, 401, 404

Request

Name

In

Type

Description

firewall_policy_id

path

string

The ID of the firewall policy.

firewall_policy

body

object

A firewall_policy object.

audited (Optional)

body

boolean

Each time that the firewall policy or its associated rules are changed, the API sets this attribute to false. To audit the policy, explicitly set this attribute to true.

description (Optional)

body

string

A human-readable name of the firewall policy.

firewall_rules (Optional)

body

array

A list of the IDs of the firewall rules associated with the firewall policy.

name (Optional)

body

string

A human-readable name of the firewall policy.

project_id (Optional)

body

string

The ID of the project that owns the resource.

shared (Optional)

body

boolean

Set to true to make this firewall policy visible to other projects. Default is false.

tenant_id (Optional)

body

string

The ID of the project that owns the resource.

Request Example

{
    "firewall_policy": {
        "firewall_rules": [
            "a08ef905-0ff6-4784-8374-175fffe7dade",
            "8722e0e0-9cc9-4490-9660-8c9a5732fbb0"
        ]
    }
}

Response Parameters

Name

In

Type

Description

firewall_policy

body

object

A firewall_policy object.

audited

body

boolean

Each time that the firewall policy or its associated rules are changed, the API sets this attribute to false. To audit the policy, explicitly set this attribute to true.

description

body

string

A human-readable name of the firewall policy.

firewall_rules

body

array

A list of the IDs of the firewall rules associated with the firewall policy.

id

body

string

The ID of the firewall policy.

name

body

string

A human-readable name of the firewall policy.

shared

body

boolean

Set to true to make this firewall policy visible to other projects. Default is false.

project_id

body

string

The ID of the project that owns the resource.

tenant_id

body

string

The ID of the project that owns the resource.

Response Example

{
    "firewall_policy": {
        "audited": false,
        "description": "",
        "firewall_rules": [
            "a08ef905-0ff6-4784-8374-175fffe7dade",
            "8722e0e0-9cc9-4490-9660-8c9a5732fbb0"
        ],
        "id": "c69933c1-b472-44f9-8226-30dc4ffd454c",
        "name": "test-policy",
        "project_id": "45977fa2dbd7482098dd68d0d8970117",
        "shared": false,
        "tenant_id": "45977fa2dbd7482098dd68d0d8970117"
    }
}
DELETE
/v2.0/fwaas/firewall_policies/{firewall_policy_id}

Delete firewall policy

Deletes a firewall policy.

Normal response codes: 204

Error response codes: 401, 404, 409

Request

Name

In

Type

Description

firewall_policy_id

path

string

The ID of the firewall policy.

Response

There is no body content for the response of a successful DELETE request.

GET
/v2.0/fwaas/firewall_rules

List firewall rules

Lists all firewall rules.

The list might be empty.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401, 403

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

firewall_rules

body

object

A list of firewall_rule objects.

action

body

string

The action that the API performs on traffic that matches the firewall rule. Valid values are allow or deny. Default is deny.

description

body

string

A human-readable description of the firewall rule.

destination_firewall_group_id

body

string

The ID of the remote destination firewall group.

destination_ip_address

body

string

The destination IPv4 or IPv6 address or CIDR for the firewall rule. No default.

destination_port

body

string

The destination port or port range for the firewall rule. A valid value is a port number, as an integer, or a port range, in the format of a : separated range. For a port range, include both ends of the range. For example, 80:90.

enabled

body

boolean

Set to false to disable this rule in the firewall policy. Facilitates selectively turning off rules without having to disassociate the rule from the firewall policy. Valid values are true or false. Default is true.

firewall_policy_id

body

string

The ID of the firewall policy.

id

body

string

The ID of the firewall rule.

ip_version

body

integer

The IP protocol version for the firewall rule. Valid values are 4 or 6. Default is 4.

name

body

string

A human-readable name of the firewall rule.

project_id

body

string

The ID of the project that owns the resource.

protocol

body

string

The IP protocol for the firewall rule. Possible values are icmp, tcp, udp, or null.

shared

body

boolean

Indicates whether this firewall rule is shared across all projects.

source_firewall_group_id

body

string

The ID of the remote source firewall group.

source_ip_address

body

string

The source IPv4 or IPv6 address or CIDR for the firewall rule. No default.

source_port

body

string

The source port or port range for the firewall rule. A valid value is a port number, as an integer, or a port range, in the format of a : separated range. For a port range, include both ends of the range. For example, 80:90.

tenant_id

body

string

The ID of the project that owns the resource.

Response Example

{
    "firewall_rules": [
        {
            "action": "allow",
            "description": "",
            "destination_firewall_group_id": null,
            "destination_ip_address": null,
            "destination_port": "80",
            "enabled": true,
            "firewall_policy_id": "c69933c1-b472-44f9-8226-30dc4ffd454c",
            "id": "8722e0e0-9cc9-4490-9660-8c9a5732fbb0",
            "ip_version": 4,
            "name": "ALLOW_HTTP",
            "position": 1,
            "project_id": "45977fa2dbd7482098dd68d0d8970117",
            "protocol": "tcp",
            "shared": false,
            "source_firewall_group_id": null,
            "source_ip_address": null,
            "source_port": null,
            "tenant_id": "45977fa2dbd7482098dd68d0d8970117"
        }
    ]
}
GET
/v2.0/fwaas/firewall_rules/{firewall_rule_id}

Show firewall rule details

Shows details for a firewall rule.

If the user is not an administrative user and the firewall rule object does not belong to the project, this call returns the Forbidden (403) response code.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 403, 404

Request

Name

In

Type

Description

firewall_rule_id

path

string

The ID for the firewall rule.

Response Parameters

Name

In

Type

Description

firewall_rule

body

object

A firewall_rule object.

action

body

string

The action that the API performs on traffic that matches the firewall rule. Valid values are allow or deny. Default is deny.

description

body

string

A human-readable description of the firewall rule.

destination_firewall_group_id

body

string

The ID of the remote destination firewall group.

destination_ip_address

body

string

The destination IPv4 or IPv6 address or CIDR for the firewall rule. No default.

destination_port

body

string

The destination port or port range for the firewall rule. A valid value is a port number, as an integer, or a port range, in the format of a : separated range. For a port range, include both ends of the range. For example, 80:90.

enabled

body

boolean

Set to false to disable this rule in the firewall policy. Facilitates selectively turning off rules without having to disassociate the rule from the firewall policy. Valid values are true or false. Default is true.

firewall_policy_id

body

string

The ID of the firewall policy.

id

body

string

The ID of the firewall rule.

ip_version

body

integer

The IP protocol version for the firewall rule. Valid values are 4 or 6. Default is 4.

name

body

string

A human-readable name of the firewall rule.

project_id

body

string

The ID of the project that owns the resource.

protocol

body

string

The IP protocol for the firewall rule. Possible values are icmp, tcp, udp, or null.

shared

body

boolean

Indicates whether this firewall rule is shared across all projects.

source_firewall_group_id

body

string

The ID of the remote source firewall group.

source_ip_address

body

string

The source IPv4 or IPv6 address or CIDR for the firewall rule. No default.

source_port

body

string

The source port or port range for the firewall rule. A valid value is a port number, as an integer, or a port range, in the format of a : separated range. For a port range, include both ends of the range. For example, 80:90.

tenant_id

body

string

The ID of the project that owns the resource.

Response Example

{
    "firewall_rule": {
        "action": "allow",
        "description": "",
        "destination_firewall_group_id": null,
        "destination_ip_address": null,
        "destination_port": "80",
        "enabled": true,
        "firewall_policy_id": null,
        "id": "8722e0e0-9cc9-4490-9660-8c9a5732fbb0",
        "ip_version": 4,
        "name": "ALLOW_HTTP",
        "position": null,
        "project_id": "45977fa2dbd7482098dd68d0d8970117",
        "protocol": "tcp",
        "shared": false,
        "source_firewall_group_id": null,
        "source_ip_address": null,
        "source_port": null,
        "tenant_id": "45977fa2dbd7482098dd68d0d8970117"
    }
}
POST
/v2.0/fwaas/firewall_rules

Create firewall rule

Creates a firewall rule.

Normal response codes: 201

Error response codes: 400, 401

Request

Name

In

Type

Description

firewall_rule

body

object

A firewall_rule object.

action (Optional)

body

string

The action that the API performs on traffic that matches the firewall rule. Valid values are allow or deny. Default is deny.

description (Optional)

body

string

A human-readable description of the firewall rule.

destination_firewall_group_id (Optional)

body

string

The ID of the remote destination firewall group.

destination_ip_address (Optional)

body

string

The destination IPv4 or IPv6 address or CIDR for the firewall rule. No default.

destination_port (Optional)

body

string

The destination port or port range for the firewall rule. A valid value is a port number, as an integer, or a port range, in the format of a : separated range. For a port range, include both ends of the range. For example, 80:90.

enabled (Optional)

body

boolean

Set to false to disable this rule in the firewall policy. Facilitates selectively turning off rules without having to disassociate the rule from the firewall policy. Valid values are true or false. Default is true.

ip_version (Optional)

body

integer

The IP protocol version for the firewall rule. Valid values are 4 or 6. Default is 4.

name (Optional)

body

string

A human-readable name of the firewall rule.

project_id (Optional)

body

string

The ID of the project that owns the resource.

protocol (Optional)

body

string

The IP protocol for the firewall rule. Possible values are icmp, tcp, udp, or null.

shared (Optional)

body

boolean

Indicates whether this firewall rule is shared across all projects.

source_firewall_group_id (Optional)

body

string

The ID of the remote source firewall group.

source_ip_address (Optional)

body

string

The source IPv4 or IPv6 address or CIDR for the firewall rule. No default.

source_port (Optional)

body

string

The source port or port range for the firewall rule. A valid value is a port number, as an integer, or a port range, in the format of a : separated range. For a port range, include both ends of the range. For example, 80:90.

tenant_id (Optional)

body

string

The ID of the project that owns the resource.

Request Example

{
    "firewall_rule": {
        "action": "allow",
        "destination_port": "80",
        "enabled": true,
        "name": "ALLOW_HTTP",
        "protocol": "tcp"
    }
}

Response Parameters

Name

In

Type

Description

firewall_rule

body

object

A firewall_rule object.

action

body

string

The action that the API performs on traffic that matches the firewall rule. Valid values are allow or deny. Default is deny.

description

body

string

A human-readable description of the firewall rule.

destination_firewall_group_id

body

string

The ID of the remote destination firewall group.

destination_ip_address

body

string

The destination IPv4 or IPv6 address or CIDR for the firewall rule. No default.

destination_port

body

string

The destination port or port range for the firewall rule. A valid value is a port number, as an integer, or a port range, in the format of a : separated range. For a port range, include both ends of the range. For example, 80:90.

enabled

body

boolean

Set to false to disable this rule in the firewall policy. Facilitates selectively turning off rules without having to disassociate the rule from the firewall policy. Valid values are true or false. Default is true.

firewall_policy_id

body

string

The ID of the firewall policy.

id

body

string

The ID of the firewall rule.

ip_version

body

integer

The IP protocol version for the firewall rule. Valid values are 4 or 6. Default is 4.

name

body

string

A human-readable name of the firewall rule.

project_id

body

string

The ID of the project that owns the resource.

protocol

body

string

The IP protocol for the firewall rule. Possible values are icmp, tcp, udp, or null.

shared

body

boolean

Indicates whether this firewall rule is shared across all projects.

source_firewall_group_id

body

string

The ID of the remote source firewall group.

source_ip_address

body

string

The source IPv4 or IPv6 address or CIDR for the firewall rule. No default.

source_port

body

string

The source port or port range for the firewall rule. A valid value is a port number, as an integer, or a port range, in the format of a : separated range. For a port range, include both ends of the range. For example, 80:90.

tenant_id

body

string

The ID of the project that owns the resource.

Response Example

{
    "firewall_rule": {
        "action": "deny",
        "description": "",
        "destination_firewall_group_id": null,
        "destination_ip_address": null,
        "destination_port": null,
        "enabled": true,
        "id": "1fd59b2f-cc87-435f-a244-1df2c0cc3f70",
        "ip_version": 4,
        "name": "rule3",
        "project_id": "95573613ec554b4b8df9f2679c64557b",
        "protocol": null,
        "shared": false,
        "source_firewall_group_id": null,
        "source_ip_address": null,
        "source_port": null,
        "tenant_id": "95573613ec554b4b8df9f2679c64557b"
    }
}
PUT
/v2.0/fwaas/firewall_rules/{firewall_rule_id}

Update firewall rule

Updates a firewall rule.

Normal response codes: 200

Error response codes: 400, 401, 404

Request

Name

In

Type

Description

firewall_rule_id

path

string

The ID for the firewall rule.

firewall_rule

body

object

A firewall_rule object.

action (Optional)

body

string

The action that the API performs on traffic that matches the firewall rule. Valid values are allow or deny. Default is deny.

description (Optional)

body

string

A human-readable description of the firewall rule.

destination_firewall_group_id (Optional)

body

string

The ID of the remote destination firewall group.

destination_ip_address (Optional)

body

string

The destination IPv4 or IPv6 address or CIDR for the firewall rule. No default.

destination_port (Optional)

body

string

The destination port or port range for the firewall rule. A valid value is a port number, as an integer, or a port range, in the format of a : separated range. For a port range, include both ends of the range. For example, 80:90.

enabled (Optional)

body

boolean

Set to false to disable this rule in the firewall policy. Facilitates selectively turning off rules without having to disassociate the rule from the firewall policy. Valid values are true or false. Default is true.

firewall_policy_id

body

string

The ID of the firewall policy.

ip_version (Optional)

body

integer

The IP protocol version for the firewall rule. Valid values are 4 or 6. Default is 4.

name (Optional)

body

string

A human-readable name of the firewall rule.

project_id (Optional)

body

string

The ID of the project that owns the resource.

protocol (Optional)

body

string

The IP protocol for the firewall rule. Possible values are icmp, tcp, udp, or null.

shared (Optional)

body

boolean

Indicates whether this firewall rule is shared across all projects.

source_firewall_group_id (Optional)

body

string

The ID of the remote source firewall group.

source_ip_address (Optional)

body

string

The source IPv4 or IPv6 address or CIDR for the firewall rule. No default.

source_port (Optional)

body

string

The source port or port range for the firewall rule. A valid value is a port number, as an integer, or a port range, in the format of a : separated range. For a port range, include both ends of the range. For example, 80:90.

tenant_id (Optional)

body

string

The ID of the project that owns the resource.

Request Example

{
    "firewall_rule": {
        "shared": true
    }
}

Response Parameters

Name

In

Type

Description

firewall_rule

body

object

A firewall_rule object.

action

body

string

The action that the API performs on traffic that matches the firewall rule. Valid values are allow or deny. Default is deny.

description

body

string

A human-readable description of the firewall rule.

destination_firewall_group_id

body

string

The ID of the remote destination firewall group.

destination_ip_address

body

string

The destination IPv4 or IPv6 address or CIDR for the firewall rule. No default.

destination_port

body

string

The destination port or port range for the firewall rule. A valid value is a port number, as an integer, or a port range, in the format of a : separated range. For a port range, include both ends of the range. For example, 80:90.

enabled

body

boolean

Set to false to disable this rule in the firewall policy. Facilitates selectively turning off rules without having to disassociate the rule from the firewall policy. Valid values are true or false. Default is true.

firewall_policy_id

body

string

The ID of the firewall policy.

id

body

string

The ID of the firewall rule.

ip_version

body

integer

The IP protocol version for the firewall rule. Valid values are 4 or 6. Default is 4.

name

body

string

A human-readable name of the firewall rule.

project_id

body

string

The ID of the project that owns the resource.

protocol

body

string

The IP protocol for the firewall rule. Possible values are icmp, tcp, udp, or null.

shared

body

boolean

Indicates whether this firewall rule is shared across all projects.

source_firewall_group_id

body

string

The ID of the remote source firewall group.

source_ip_address

body

string

The source IPv4 or IPv6 address or CIDR for the firewall rule. No default.

source_port

body

string

The source port or port range for the firewall rule. A valid value is a port number, as an integer, or a port range, in the format of a : separated range. For a port range, include both ends of the range. For example, 80:90.

tenant_id

body

string

The ID of the project that owns the resource.

Response Example

{
    "firewall_rule": {
        "action": "allow",
        "description": "",
        "destination_firewall_group_id": null,
        "destination_ip_address": null,
        "destination_port": "80",
        "enabled": true,
        "firewall_policy_id": "c69933c1-b472-44f9-8226-30dc4ffd454c",
        "id": "8722e0e0-9cc9-4490-9660-8c9a5732fbb0",
        "ip_version": 4,
        "name": "ALLOW_HTTP",
        "position": 1,
        "project_id": "45977fa2dbd7482098dd68d0d8970117",
        "protocol": "tcp",
        "shared": true,
        "source_firewall_group_id": null,
        "source_ip_address": null,
        "source_port": null,
        "tenant_id": "45977fa2dbd7482098dd68d0d8970117"
    }
}
DELETE
/v2.0/fwaas/firewall_rules/{firewall_rule_id}

Delete firewall rule

Deletes a firewall rule. samples/firewall-v2/firewall-policy-create-response.json

Normal response codes: 204

Error response codes: 401, 404, 409

Request

Name

In

Type

Description

firewall_rule_id

path

string

The ID for the firewall rule.

PUT
/v2.0/fwaas/firewall_policies/{firewall_policy_id}/insert_rule

Insert rule into a firewall policy

Insert firewall rule into a policy.

A firewall_rule_id is inserted relative to the position of the firewall_rule_id set in insert_before or insert_after. If insert_before is set, insert_after is ignored. If both insert_before and insert_after are not set, the new firewall_rule_id is inserted as the first rule of the policy.

Normal response codes: 200

Error response codes: 400, 401, 404, 409

Request

Name

In

Type

Description

firewall_policy_id

path

string

The ID of the firewall policy.

firewall_rule_id

body

string

The ID of the firewall rule.

insert_after

body

string

The ID of the firewall_rule to insert the new rule after. The new rule will be inserted immediately after the specified firewall_rule. If both before and after values are supplied, the after value will be ignored. To insert a rule into a policy with no rules yet, the both the before and the after values must be “”.

insert_before

body

string

The ID of the firewall_rule to insert the new rule before. The new rule will be inserted immediately before the specified firewall_rule. If both before and after values are supplied, the after value will be ignored. To insert a rule into a policy with no rules yet, the both the before and the after values must be “”.

Request Example

{
    "firewall_rule_id": "7bc34b8c-8d3b-4ada-a9c8-1f4c11c65692",
    "insert_after": "a08ef905-0ff6-4784-8374-175fffe7dade",
    "insert_before": ""
}

Response Parameters

Name

In

Type

Description

audited

body

boolean

Each time that the firewall policy or its associated rules are changed, the API sets this attribute to false. To audit the policy, explicitly set this attribute to true.

description

body

string

A human-readable name of the firewall policy.

firewall_rules

body

array

A list of the IDs of the firewall rules associated with the firewall policy.

id

body

string

The ID of the firewall policy.

name

body

string

A human-readable name of the firewall policy.

project_id

body

string

The ID of the project that owns the resource.

shared

body

boolean

Set to true to make this firewall policy visible to other projects. Default is false.

tenant_id

body

string

The ID of the project that owns the resource.

Response Example

{
  "audited": false,
  "description": "",
  "firewall_rules": [
    "acbdfead-eca2-4456-838c-8b531e47b9c7"
  ],
  "id": "c9e15d6e-b6ba-4ef4-8715-985d1f100467",
  "name": "policy2",
  "shared": false,
  "project_id": "95573613ec554b4b8df9f2679c64557b",
  "tenant_id": "95573613ec554b4b8df9f2679c64557b"
}
PUT
/v2.0/fwaas/firewall_policies/{firewall_policy_id}/remove_rule

Remove rule from firewall policy

Remove firewall rule from a policy.

Normal response codes: 200

Error response codes: 400, 401, 404

Request

Name

In

Type

Description

firewall_policy_id

path

string

The ID of the firewall policy.

firewall_rule_id

body

string

The ID of the firewall rule.

Request Example

{
    "firewall_rule_id": "7bc34b8c-8d3b-4ada-a9c8-1f4c11c65692"
}

Response Parameters

Name

In

Type

Description

audited

body

boolean

Each time that the firewall policy or its associated rules are changed, the API sets this attribute to false. To audit the policy, explicitly set this attribute to true.

description

body

string

A human-readable name of the firewall policy.

firewall_rules

body

array

A list of the IDs of the firewall rules associated with the firewall policy.

id

body

string

The ID of the firewall policy.

name

body

string

A human-readable name of the firewall policy.

project_id

body

string

The ID of the project that owns the resource.

shared

body

boolean

Set to true to make this firewall policy visible to other projects. Default is false.

tenant_id

body

string

The ID of the project that owns the resource.

Response Example

{
  "audited": false,
  "description": "",
  "firewall_rules": [],
  "id": "c9e15d6e-b6ba-4ef4-8715-985d1f100467",
  "name": "policy2",
  "project_id": "95573613ec554b4b8df9f2679c64557b",
  "shared": false,
  "tenant_id": "95573613ec554b4b8df9f2679c64557b"
}

RBAC Policies

Lists, shows details for, creates, updates, and deletes RBAC policies.

The presence of the rbac-security-groups extension extends this API to support object types of security_group.

The presence of the rbac-address-scope extension extends this API to support object types of address-scope.

The presence of the rbac-subnetpool extension extends this API to support object types of subnetpool.

The presence of the rbac-address-group extension extends this API to support object types of address-group.

The presence of the rbac-bgpvpn extension extends this API to support object types of bgpvpn.

GET
/v2.0/rbac-policies/{rbac_policy_id}

Show RBAC policy details

Show details for a given RBAC policy.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

rbac_policy_id

path

string

The ID of the RBAC policy.

Response Parameters

Name

In

Type

Description

target_tenant

body

string

The ID of the tenant to which the RBAC policy will be enforced.

tenant_id

body

string

The ID of the project that owns the resource.

object_type

body

string

The type of the object that the RBAC policy affects. Types include qos-policy, network, security-group, address-scope, subnetpool or address-group.

object_id

body

string

The ID of the object_type resource. An object_type of network returns a network ID, an object_type of qos-policy returns a QoS policy ID, an object_type of security-group returns a security group ID, an object_type of address-scope returns a address scope ID, an object_type of subnetpool returns a subnetpool ID and an object_type of address-group returns an address group ID.

action

body

string

Action for the RBAC policy which is access_as_external or access_as_shared.

project_id

body

string

The ID of the project.

id

body

string

The ID of the RBAC policy.

Response Example

{
   "rbac_policy": {
      "target_tenant": "*",
      "tenant_id": "3de27ce0a2a54cc6ae06dc62dd0ec832",
      "object_type": "network",
      "object_id": "1f32f072-4d17-4811-b619-3623d018bd40",
      "action": "access_as_external",
      "project_id": "3de27ce0a2a54cc6ae06dc62dd0ec832",
      "id": "6d4c666e-1aad-465e-b670-4d112b760137"
   }
}
PUT
/v2.0/rbac-policies/{rbac_policy_id}

Update RBAC policy

Update RBAC policy for given tenant.

Normal response codes: 200

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

rbac_policy_id

path

string

The ID of the RBAC policy.

target_tenant

body

string

The ID of the tenant to which the RBAC policy will be enforced. Please note that Neutron does not perform any type of validation that the value provided is actually the ID of the existing project. If, for example, the name of the project is provided here, it will be accepted by the Neutron API, but the RBAC rule created will not work as expected.

Request Example

{
   "rbac_policy": {
      "target_tenant": "*"
   }
}

Response Parameters

Name

In

Type

Description

target_tenant

body

string

The ID of the tenant to which the RBAC policy will be enforced.

tenant_id

body

string

The ID of the project that owns the resource.

object_type

body

string

The type of the object that the RBAC policy affects. Types include qos-policy, network, security-group, address-scope, subnetpool or address-group.

object_id

body

string

The ID of the object_type resource. An object_type of network returns a network ID, an object_type of qos-policy returns a QoS policy ID, an object_type of security-group returns a security group ID, an object_type of address-scope returns a address scope ID, an object_type of subnetpool returns a subnetpool ID and an object_type of address-group returns an address group ID.

action

body

string

Action for the RBAC policy which is access_as_external or access_as_shared.

project_id

body

string

The ID of the project.

id

body

string

The ID of the RBAC policy.

Response Example

{
   "rbac_policy": {
      "target_tenant": "*",
      "tenant_id": "3de27ce0a2a54cc6ae06dc62dd0ec832",
      "object_type": "network",
      "object_id": "1f32f072-4d17-4811-b619-3623d018bd40",
      "action": "access_as_external",
      "project_id": "3de27ce0a2a54cc6ae06dc62dd0ec832",
      "id": "6d4c666e-1aad-465e-b670-4d112b760137"
   }
}
DELETE
/v2.0/rbac-policies/{rbac_policy_id}

Delete RBAC policy

Delete an RBAC policy.

Normal response codes: 204

Error response codes: 401, 404, 409

Request

Name

In

Type

Description

rbac_policy_id

path

string

The ID of the RBAC policy.

Response

There is no body content for the response of a successful DELETE request.

GET
/v2.0/rbac-policies

List RBAC policies

List RBAC policies that belong to a given tenant.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

target_tenant (Optional)

query

string

Filter the RBAC policy list result by the ID of the tenant to which the RBAC policy will be enforced.

tenant_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

object_type (Optional)

query

string

Filter the RBAC policy list result by the type of the object that the RBAC policy affects. Types include qos-policy, network, security-group, address-scope, subnetpool, address-group or bgpvpn.

object_id (Optional)

query

string

Filter the RBAC policy list result by the ID of the object_type resource. An object_type of network returns a network ID, an object_type of qos-policy returns a QoS policy ID, an object_type of security-group returns a security group ID, an object_type` of address-scope returns a address scope ID, an object_type of subnetpool returns a subnetpool ID, an object_type of address-group returns an address group ID and an object_type of bgpvpn returns a bgpvpn ID.

action (Optional)

query

string

Filter the RBAC policy list result by the action for the RBAC policy which is access_as_external or access_as_shared.

project_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

id (Optional)

query

string

Filter the list result by the ID of the resource.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a RBAC policy attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • action

  • id

  • object_id

  • target_tenant

  • tenant_id

  • project_id

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

target_tenant

body

string

The ID of the tenant to which the RBAC policy will be enforced.

tenant_id

body

string

The ID of the project that owns the resource.

object_type

body

string

The type of the object that the RBAC policy affects. Types include qos-policy, network, security-group, address-scope, subnetpool or address-group.

object_id

body

string

The ID of the object_type resource. An object_type of network returns a network ID, an object_type of qos-policy returns a QoS policy ID, an object_type of security-group returns a security group ID, an object_type of address-scope returns a address scope ID, an object_type of subnetpool returns a subnetpool ID and an object_type of address-group returns an address group ID.

action

body

string

Action for the RBAC policy which is access_as_external or access_as_shared.

project_id

body

string

The ID of the project.

id

body

string

The ID of the RBAC policy.

Response Example

{
   "rbac_policies": [
      {
         "target_tenant": "*",
         "tenant_id": "3de27ce0a2a54cc6ae06dc62dd0ec832",
         "object_type": "network",
         "object_id": "1f32f072-4d17-4811-b619-3623d018bd40",
         "action": "access_as_external",
         "project_id": "3de27ce0a2a54cc6ae06dc62dd0ec832",
         "id":"6d4c666e-1aad-465e-b670-4d112b760137"
      }
   ]
}
POST
/v2.0/rbac-policies

Create RBAC policy

Create RBAC policy for given tenant.

Normal response codes: 201

Error response codes: 400, 401

Request

Name

In

Type

Description

target_tenant

body

string

The ID of the tenant to which the RBAC policy will be enforced. Please note that Neutron does not perform any type of validation that the value provided is actually the ID of the existing project. If, for example, the name of the project is provided here, it will be accepted by the Neutron API, but the RBAC rule created will not work as expected.

object_type

body

string

The type of the object that the RBAC policy affects. Types include qos-policy, network, security-group, address-scope, subnetpool or address-group.

object_id

body

string

The ID of the object_type resource. An object_type of network returns a network ID, an object_type of qos-policy returns a QoS policy ID, an object_type of security-group returns a security group ID, an object_type of address-scope returns a address scope ID, an object_type of subnetpool returns a subnetpool ID and an object_type of address-group returns an address group ID.

action

body

string

Action for the RBAC policy which is access_as_external or access_as_shared.

Request Example

{
   "rbac_policy": {
      "action": "access_as_shared",
      "object_type": "network",
      "target_tenant": "0670b690f27e47a58b6a479d26004715",
      "object_id": "1f32f072-4d17-4811-b619-3623d018bd40"
   }
}

Response Parameters

Name

In

Type

Description

target_tenant

body

string

The ID of the tenant to which the RBAC policy will be enforced.

tenant_id

body

string

The ID of the project that owns the resource.

object_type

body

string

The type of the object that the RBAC policy affects. Types include qos-policy, network, security-group, address-scope, subnetpool or address-group.

object_id

body

string

The ID of the object_type resource. An object_type of network returns a network ID, an object_type of qos-policy returns a QoS policy ID, an object_type of security-group returns a security group ID, an object_type of address-scope returns a address scope ID, an object_type of subnetpool returns a subnetpool ID and an object_type of address-group returns an address group ID.

action

body

string

Action for the RBAC policy which is access_as_external or access_as_shared.

project_id

body

string

The ID of the project.

id

body

string

The ID of the RBAC policy.

Response Example

{
   "rbac_policy": {
      "target_tenant": "0670b690f27e47a58b6a479d26004715",
      "tenant_id": "3de27ce0a2a54cc6ae06dc62dd0ec832",
      "object_type": "network",
      "object_id": "1f32f072-4d17-4811-b619-3623d018bd40",
      "action": "access_as_shared",
      "project_id": "3de27ce0a2a54cc6ae06dc62dd0ec832",
      "id": "2cf7523a-93b5-4e69-9360-6c6bf986bb7c"
   }
}

Security group rules (security-group-rules)

Lists, creates, shows information for, and deletes security group rules.

Resource timestamps

The standard-attr-timestamp extension adds the created_at and updated_at attributes to all resources that have standard attributes.

Remote address group id

The extension security-groups-remote-address-group adds a new field remote_address_group_id in security group rules.

Belongs to the project’s default security group

This read only flag determines if the security group rule belongs to the project default security group. Is a syntethic field set by the server.

GET
/v2.0/security-group-rules

List security group rules

Lists a summary of all OpenStack Networking security group rules that the project can access.

The list provides the ID for each security group rule.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

remote_group_id (Optional)

query

string

Filter the security group rule list result by the ID of the remote group that associates with this security group rule.

direction (Optional)

query

string

Filter the security group rule list result by the direction in which the security group rule is applied, which is ingress or egress.

protocol (Optional)

query

string

Filter the security group rule list result by the IP protocol.

ethertype (Optional)

query

string

Filter the security group rule list result by the ethertype of network traffic. The value must be IPv4 or IPv6.

port_range_max (Optional)

query

integer

Filter the security group rule list result by the maximum port number in the range that is matched by the security group rule.

security_group_id (Optional)

query

string

Filter the security group rule list result by the ID of the security group that associates with this security group rule.

tenant_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

project_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

port_range_min (Optional)

query

integer

Filter the security group rule list result by the minimum port number in the range that is matched by the security group rule.

remote_ip_prefix (Optional)

query

string

Filter the list result by the remote IP prefix that is matched by this security group rule.

revision_number (Optional)

query

integer

Filter the list result by the revision number of the resource.

id (Optional)

query

string

Filter the list result by the ID of the resource.

description (Optional)

query

string

Filter the list result by the human-readable description of the resource.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a security group rule attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • direction

  • ethertype

  • id

  • port_range_max

  • port_range_min

  • protocol

  • remote_group_id

  • remote_ip_prefix

  • security_group_id

  • tenant_id

  • project_id

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

security_group_rules

body

array

A list of security_group_rule objects. Refer to Security group rules for details.

remote_group_id

body

string

The remote group UUID to associate with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body.

remote_address_group_id

body

string

The remote address group UUID that is associated with this security group rule.

direction

body

string

Ingress or egress, which is the direction in which the security group rule is applied.

protocol

body

string

The IP protocol can be represented by a string, an integer, or null. Valid string or integer values are any or 0, ah or 51, dccp or 33, egp or 8, esp or 50, gre or 47, icmp or 1, icmpv6 or 58, igmp or 2, ipip or 4, ipv6-encap or 41, ipv6-frag or 44, ipv6-icmp or 58, ipv6-nonxt or 59, ipv6-opts or 60, ipv6-route or 43, ospf or 89, pgm or 113, rsvp or 46, sctp or 132, tcp or 6, udp or 17, udplite or 136, vrrp or 112. Additionally, any integer value between [0-255] is also valid. The string any (or integer 0) means all IP protocols. See the constants in neutron_lib.constants for the most up-to-date list of supported strings.

ethertype

body

string

Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.

port_range_max

body

integer

The maximum port number in the range that is matched by the security group rule. If the protocol is TCP, UDP, DCCP, SCTP or UDP-Lite this value must be greater than or equal to the port_range_min attribute value. If the protocol is ICMP, this value must be an ICMP code.

security_group_id

body

string

The security group ID to associate with this security group rule.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

port_range_min

body

integer

The minimum port number in the range that is matched by the security group rule. If the protocol is TCP, UDP, DCCP, SCTP or UDP-Lite this value must be less than or equal to the port_range_max attribute value. If the protocol is ICMP, this value must be an ICMP type.

remote_ip_prefix

body

string

The remote IP prefix that is matched by this security group rule.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

revision_number

body

integer

The revision number of the resource.

id

body

string

The ID of the security group rule.

description

body

string

A human-readable description for the resource.

belongs_to_default_sg

body

boolean

Indicates if the security group rule belongs to the default security group of the project or not.

Response Example

{
    "security_group_rules": [
        {
            "direction": "egress",
            "ethertype": "IPv6",
            "id": "3c0e45ff-adaf-4124-b083-bf390e5482ff",
            "port_range_max": null,
            "port_range_min": null,
            "protocol": null,
            "remote_group_id": null,
            "remote_address_group_id": null,
            "remote_ip_prefix": null,
            "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
            "project_id": "e4f50856753b4dc6afee5fa6b9b6c550",
            "revision_number": 1,
            "created_at": "2018-03-19T19:16:56Z",
            "updated_at": "2018-03-19T19:16:56Z",
            "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550",
            "description": "",
            "belongs_to_default_sg": false
        },
        {
            "direction": "egress",
            "ethertype": "IPv4",
            "id": "93aa42e5-80db-4581-9391-3a608bd0e448",
            "port_range_max": null,
            "port_range_min": null,
            "protocol": null,
            "remote_group_id": null,
            "remote_address_group_id": null,
            "remote_ip_prefix": null,
            "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
            "project_id": "e4f50856753b4dc6afee5fa6b9b6c550",
            "revision_number": 1,
            "created_at": "2018-03-19T19:16:56Z",
            "updated_at": "2018-03-19T19:16:56Z",
            "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550",
            "description": "",
            "belongs_to_default_sg": false
        },
        {
            "direction": "ingress",
            "ethertype": "IPv6",
            "id": "c0b09f00-1d49-4e64-a0a7-8a186d928138",
            "port_range_max": null,
            "port_range_min": null,
            "protocol": null,
            "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
            "remote_address_group_id": null,
            "remote_ip_prefix": null,
            "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
            "project_id": "e4f50856753b4dc6afee5fa6b9b6c550",
            "revision_number": 2,
            "created_at": "2018-03-19T19:16:56Z",
            "updated_at": "2018-03-19T19:16:56Z",
            "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550",
            "description": "",
            "belongs_to_default_sg": false
        },
        {
            "direction": "ingress",
            "ethertype": "IPv4",
            "id": "f7d45c89-008e-4bab-88ad-d6811724c51c",
            "port_range_max": null,
            "port_range_min": null,
            "protocol": null,
            "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
            "remote_address_group_id": null,
            "remote_ip_prefix": null,
            "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
            "project_id": "e4f50856753b4dc6afee5fa6b9b6c550",
            "revision_number": 1,
            "created_at": "2018-03-19T19:16:56Z",
            "updated_at": "2018-03-19T19:16:56Z",
            "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550",
            "description": "",
            "belongs_to_default_sg": false
        }
    ]
}
POST
/v2.0/security-group-rules

Create security group rule

Creates an OpenStack Networking security group rule.

Normal response codes: 201

Error response codes: 400, 401, 404, 409

Request

Name

In

Type

Description

security_group_rule

body

object

A security_group_rule object.

remote_group_id (Optional)

body

string

The remote group UUID to associate with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body.

remote_address_group_id (Optional)

query

string

UUID of the remote address group that associates with the security group rule created from this template.

direction

body

string

Ingress or egress, which is the direction in which the security group rule is applied.

protocol (Optional)

body

string

The IP protocol can be represented by a string, an integer, or null. Valid string or integer values are any or 0, ah or 51, dccp or 33, egp or 8, esp or 50, gre or 47, icmp or 1, icmpv6 or 58, igmp or 2, ipip or 4, ipv6-encap or 41, ipv6-frag or 44, ipv6-icmp or 58, ipv6-nonxt or 59, ipv6-opts or 60, ipv6-route or 43, ospf or 89, pgm or 113, rsvp or 46, sctp or 132, tcp or 6, udp or 17, udplite or 136, vrrp or 112. Additionally, any integer value between [0-255] is also valid. The string any (or integer 0) means all IP protocols. See the constants in neutron_lib.constants for the most up-to-date list of supported strings.

ethertype (Optional)

body

string

Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.

port_range_max (Optional)

body

integer

The maximum port number in the range that is matched by the security group rule. If the protocol is TCP, UDP, DCCP, SCTP or UDP-Lite this value must be greater than or equal to the port_range_min attribute value. If the protocol is ICMP, this value must be an ICMP code.

security_group_id

body

string

The security group ID to associate with this security group rule.

port_range_min (Optional)

body

integer

The minimum port number in the range that is matched by the security group rule. If the protocol is TCP, UDP, DCCP, SCTP or UDP-Lite this value must be less than or equal to the port_range_max attribute value. If the protocol is ICMP, this value must be an ICMP type.

remote_ip_prefix (Optional)

body

string

The remote IP prefix that is matched by this security group rule.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

Request Example

{
    "security_group_rule": {
        "direction": "ingress",
        "port_range_min": "80",
        "ethertype": "IPv4",
        "port_range_max": "80",
        "protocol": "tcp",
        "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
        "remote_address_group_id": "a9baa1eb-0614-4d68-870e-fec6d8f8c221",
        "security_group_id": "a7734e61-b545-452d-a3cd-0189cbd9747a"
    }
}

Response Parameters

Name

In

Type

Description

security_group_rule

body

object

A security_group_rule object.

remote_group_id

body

string

The remote group UUID to associate with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body.

remote_address_group_id

body

string

The remote address group UUID that is associated with this security group rule.

direction

body

string

Ingress or egress, which is the direction in which the security group rule is applied.

protocol

body

string

The IP protocol can be represented by a string, an integer, or null. Valid string or integer values are any or 0, ah or 51, dccp or 33, egp or 8, esp or 50, gre or 47, icmp or 1, icmpv6 or 58, igmp or 2, ipip or 4, ipv6-encap or 41, ipv6-frag or 44, ipv6-icmp or 58, ipv6-nonxt or 59, ipv6-opts or 60, ipv6-route or 43, ospf or 89, pgm or 113, rsvp or 46, sctp or 132, tcp or 6, udp or 17, udplite or 136, vrrp or 112. Additionally, any integer value between [0-255] is also valid. The string any (or integer 0) means all IP protocols. See the constants in neutron_lib.constants for the most up-to-date list of supported strings.

ethertype

body

string

Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.

port_range_max

body

integer

The maximum port number in the range that is matched by the security group rule. If the protocol is TCP, UDP, DCCP, SCTP or UDP-Lite this value must be greater than or equal to the port_range_min attribute value. If the protocol is ICMP, this value must be an ICMP code.

security_group_id

body

string

The security group ID to associate with this security group rule.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

port_range_min

body

integer

The minimum port number in the range that is matched by the security group rule. If the protocol is TCP, UDP, DCCP, SCTP or UDP-Lite this value must be less than or equal to the port_range_max attribute value. If the protocol is ICMP, this value must be an ICMP type.

remote_ip_prefix

body

string

The remote IP prefix that is matched by this security group rule.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

revision_number

body

integer

The revision number of the resource.

id

body

string

The ID of the security group rule.

description

body

string

A human-readable description for the resource.

belongs_to_default_sg

body

boolean

Indicates if the security group rule belongs to the default security group of the project or not.

Response Example

{
    "security_group_rule": {
        "direction": "ingress",
        "ethertype": "IPv4",
        "id": "2bc0accf-312e-429a-956e-e4407625eb62",
        "port_range_max": 80,
        "port_range_min": 80,
        "protocol": "tcp",
        "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
        "remote_address_group_id": "a9baa1eb-0614-4d68-870e-fec6d8f8c221",
        "remote_ip_prefix": null,
        "security_group_id": "a7734e61-b545-452d-a3cd-0189cbd9747a",
        "project_id": "e4f50856753b4dc6afee5fa6b9b6c550",
        "revision_number": 1,
        "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550",
        "created_at": "2018-03-19T19:16:56Z",
        "updated_at": "2018-03-19T19:16:56Z",
        "description": "",
        "belongs_to_default_sg": false
    }
}
POST
/v2.0/security-group-rules

Bulk create security group rule

Creates multiple OpenStack Networking security group rules in a single request. Specify a list of security group rules in the request body.

Guarantees the atomic completion of the bulk operation.

Normal response codes: 201

Error response codes: 400, 401, 404, 409

Request

Name

In

Type

Description

security_group_rules

body

array

A list of security_group_rule objects. Refer to Security group rules for details.

remote_group_id (Optional)

body

string

The remote group UUID to associate with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body.

remote_address_group_id (Optional)

query

string

UUID of the remote address group that associates with the security group rule created from this template.

direction

body

string

Ingress or egress, which is the direction in which the security group rule is applied.

protocol (Optional)

body

string

The IP protocol can be represented by a string, an integer, or null. Valid string or integer values are any or 0, ah or 51, dccp or 33, egp or 8, esp or 50, gre or 47, icmp or 1, icmpv6 or 58, igmp or 2, ipip or 4, ipv6-encap or 41, ipv6-frag or 44, ipv6-icmp or 58, ipv6-nonxt or 59, ipv6-opts or 60, ipv6-route or 43, ospf or 89, pgm or 113, rsvp or 46, sctp or 132, tcp or 6, udp or 17, udplite or 136, vrrp or 112. Additionally, any integer value between [0-255] is also valid. The string any (or integer 0) means all IP protocols. See the constants in neutron_lib.constants for the most up-to-date list of supported strings.

ethertype (Optional)

body

string

Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.

port_range_max (Optional)

body

integer

The maximum port number in the range that is matched by the security group rule. If the protocol is TCP, UDP, DCCP, SCTP or UDP-Lite this value must be greater than or equal to the port_range_min attribute value. If the protocol is ICMP, this value must be an ICMP code.

security_group_id

body

string

The security group ID to associate with this security group rule.

port_range_min (Optional)

body

integer

The minimum port number in the range that is matched by the security group rule. If the protocol is TCP, UDP, DCCP, SCTP or UDP-Lite this value must be less than or equal to the port_range_max attribute value. If the protocol is ICMP, this value must be an ICMP type.

remote_ip_prefix (Optional)

body

string

The remote IP prefix that is matched by this security group rule.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

Request Example

{
    "security_group_rules": [
        {
            "direction": "ingress",
            "port_range_min": "80",
            "ethertype": "IPv4",
            "port_range_max": "80",
            "protocol": "tcp",
            "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
            "remote_address_group_id": "a9baa1eb-0614-4d68-870e-fec6d8f8c221",
            "security_group_id": "a7734e61-b545-452d-a3cd-0189cbd9747a"
        },
        {
            "direction": "ingress",
            "port_range_min": "443",
            "ethertype": "IPv4",
            "port_range_max": "443",
            "protocol": "tcp",
            "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
            "remote_address_group_id": "a9baa1eb-0614-4d68-870e-fec6d8f8c221",
            "security_group_id": "a7734e61-b545-452d-a3cd-0189cbd9747a"
        }
    ]
}

Response Parameters

Name

In

Type

Description

security_group_rules

body

array

A list of security_group_rule objects. Refer to Security group rules for details.

remote_group_id

body

string

The remote group UUID to associate with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body.

remote_address_group_id

body

string

The remote address group UUID that is associated with this security group rule.

direction

body

string

Ingress or egress, which is the direction in which the security group rule is applied.

protocol

body

string

The IP protocol can be represented by a string, an integer, or null. Valid string or integer values are any or 0, ah or 51, dccp or 33, egp or 8, esp or 50, gre or 47, icmp or 1, icmpv6 or 58, igmp or 2, ipip or 4, ipv6-encap or 41, ipv6-frag or 44, ipv6-icmp or 58, ipv6-nonxt or 59, ipv6-opts or 60, ipv6-route or 43, ospf or 89, pgm or 113, rsvp or 46, sctp or 132, tcp or 6, udp or 17, udplite or 136, vrrp or 112. Additionally, any integer value between [0-255] is also valid. The string any (or integer 0) means all IP protocols. See the constants in neutron_lib.constants for the most up-to-date list of supported strings.

ethertype

body

string

Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.

port_range_max

body

integer

The maximum port number in the range that is matched by the security group rule. If the protocol is TCP, UDP, DCCP, SCTP or UDP-Lite this value must be greater than or equal to the port_range_min attribute value. If the protocol is ICMP, this value must be an ICMP code.

security_group_id

body

string

The security group ID to associate with this security group rule.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

port_range_min

body

integer

The minimum port number in the range that is matched by the security group rule. If the protocol is TCP, UDP, DCCP, SCTP or UDP-Lite this value must be less than or equal to the port_range_max attribute value. If the protocol is ICMP, this value must be an ICMP type.

remote_ip_prefix

body

string

The remote IP prefix that is matched by this security group rule.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

revision_number

body

integer

The revision number of the resource.

id

body

string

The ID of the security group rule.

description

body

string

A human-readable description for the resource.

belongs_to_default_sg

body

boolean

Indicates if the security group rule belongs to the default security group of the project or not.

Response Example

{
    "security_group_rules": [
        {
            "direction": "ingress",
            "ethertype": "IPv4",
            "id": "2bc0accf-312e-429a-956e-e4407625eb62",
            "port_range_max": 80,
            "port_range_min": 80,
            "protocol": "tcp",
            "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
            "remote_ip_prefix": null,
            "security_group_id": "a7734e61-b545-452d-a3cd-0189cbd9747a",
            "project_id": "e4f50856753b4dc6afee5fa6b9b6c550",
            "revision_number": 1,
            "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550",
            "created_at": "2018-03-19T19:16:56Z",
            "updated_at": "2018-03-19T19:16:56Z",
            "description": "",
            "belongs_to_default_sg": false
        },
        {
            "direction": "ingress",
            "ethertype": "IPv4",
            "id": "4d4a5704-749a-4525-958e-93844d1dd9a4",
            "port_range_max": 443,
            "port_range_min": 443,
            "protocol": "tcp",
            "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
            "remote_ip_prefix": null,
            "security_group_id": "a7734e61-b545-452d-a3cd-0189cbd9747a",
            "project_id": "e4f50856753b4dc6afee5fa6b9b6c550",
            "revision_number": 1,
            "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550",
            "created_at": "2018-03-19T19:16:56Z",
            "updated_at": "2018-03-19T19:16:56Z",
            "description": "",
            "belongs_to_default_sg": false
        }
    ]
}
GET
/v2.0/security-group-rules/{security_group_rule_id}

Show security group rule

Shows detailed information for a security group rule.

The response body contains the following information about the security group rule:

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

security_group_rule_id

path

string

The ID of the security group rule.

verbose (Optional)

query

boolean

Show detailed information.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

security_group_rule

body

object

A security_group_rule object.

remote_group_id

body

string

The remote group UUID to associate with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body.

remote_address_group_id

body

string

The remote address group UUID that is associated with this security group rule.

direction

body

string

Ingress or egress, which is the direction in which the security group rule is applied.

protocol

body

string

The IP protocol can be represented by a string, an integer, or null. Valid string or integer values are any or 0, ah or 51, dccp or 33, egp or 8, esp or 50, gre or 47, icmp or 1, icmpv6 or 58, igmp or 2, ipip or 4, ipv6-encap or 41, ipv6-frag or 44, ipv6-icmp or 58, ipv6-nonxt or 59, ipv6-opts or 60, ipv6-route or 43, ospf or 89, pgm or 113, rsvp or 46, sctp or 132, tcp or 6, udp or 17, udplite or 136, vrrp or 112. Additionally, any integer value between [0-255] is also valid. The string any (or integer 0) means all IP protocols. See the constants in neutron_lib.constants for the most up-to-date list of supported strings.

ethertype

body

string

Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.

port_range_max

body

integer

The maximum port number in the range that is matched by the security group rule. If the protocol is TCP, UDP, DCCP, SCTP or UDP-Lite this value must be greater than or equal to the port_range_min attribute value. If the protocol is ICMP, this value must be an ICMP code.

security_group_id

body

string

The security group ID to associate with this security group rule.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

port_range_min

body

integer

The minimum port number in the range that is matched by the security group rule. If the protocol is TCP, UDP, DCCP, SCTP or UDP-Lite this value must be less than or equal to the port_range_max attribute value. If the protocol is ICMP, this value must be an ICMP type.

remote_ip_prefix

body

string

The remote IP prefix that is matched by this security group rule.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

revision_number

body

integer

The revision number of the resource.

id

body

string

The ID of the security group rule.

description

body

string

A human-readable description for the resource.

belongs_to_default_sg

body

boolean

Indicates if the security group rule belongs to the default security group of the project or not.

Response Example

{
    "security_group_rule": {
        "direction": "egress",
        "ethertype": "IPv6",
        "id": "3c0e45ff-adaf-4124-b083-bf390e5482ff",
        "port_range_max": null,
        "port_range_min": null,
        "protocol": null,
        "remote_group_id": null,
        "remote_address_group_id": null,
        "remote_ip_prefix": null,
        "revision_number": 1,
        "created_at": "2018-03-19T19:16:56Z",
        "updated_at": "2018-03-19T19:16:56Z",
        "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
        "project_id": "e4f50856753b4dc6afee5fa6b9b6c550",
        "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550",
        "belongs_to_default_sg": false
    }
}
DELETE
/v2.0/security-group-rules/{security_group_rule_id}

Delete security group rule

Deletes a rule from an OpenStack Networking security group.

Normal response codes: 204

Error response codes: 401, 404, 412

Request

Name

In

Type

Description

security_group_rule_id

path

string

The ID of the security group rule.

Response

There is no body content is returned on a successful DELETE request.

Security groups (security-groups)

Lists, creates, shows information for, updates, and deletes security groups.

Resource timestamps

The standard-attr-timestamp extension adds the created_at and updated_at attributes to all resources that have standard attributes.

Tag extension

The standard-attr-tag adds Tag support for resources with standard attributes by adding the tags attribute allowing consumers to associate tags with resources.

Stateful security groups extension (stateful-security-group)

The stateful security group extension (stateful-security-group) adds the stateful field to security groups, allowing users to configure stateful or stateless security groups for ports.

A stateless security group bypasses connection tracking in the underlying firewall, potentially providing performance and simplicity benefits. On the other hand, using stateless security groups adds more complexity to rule definitions: the user now has to explicitly define rules for both directions of a duplex connection, so e.g. two rules have to be defined to allow a TCP flow: one for packets sent from a port and another one for packets received by the port.

The existing security groups will all be considered as stateful. Update of the stateful attribute is allowed when there is no port associated with the security group.

Regardless of rules defined for a stateless security group, the following protocols are expected to work: ARP, DHCP, IPv6 SLAAC / DHCPv6 stateless address configuration, IPv6 Router and Neighbour Discovery.

Note: metadata service is not enabled by default. If your workload requires metadata for configuration, make sure to create a security group rule that would allow HTTP replies from the metadata service IP address / port pair.

Shared filtering extension

The security-groups-shared-filtering extension adds the shared field to security groups and allows users to filter security groups based on the shared field.

GET
/v2.0/security-groups

List security groups

Lists OpenStack Networking security groups to which the project has access.

The response is an array of security_group objects which contains a list of security_group_rules objects.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

id (Optional)

query

string

Filter the list result by the ID of the resource.

tenant_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

project_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

revision_number (Optional)

query

integer

Filter the list result by the revision number of the resource.

name (Optional)

query

string

Filter the list result by the human-readable name of the resource.

description (Optional)

query

string

Filter the list result by the human-readable description of the resource.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a security group attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • id

  • name

  • tenant_id

  • project_id

shared (Optional)

query

boolean

Filter the security group list result based on if the security group is shared to the requestor’s project.

tags (Optional)

query

string

A list of tags to filter the list result by. Resources that match all tags in this list will be returned. Tags in query must be separated by comma.

tags-any (Optional)

query

string

A list of tags to filter the list result by. Resources that match any tag in this list will be returned. Tags in query must be separated by comma.

not-tags (Optional)

query

string

A list of tags to filter the list result by. Resources that match all tags in this list will be excluded. Tags in query must be separated by comma.

not-tags-any (Optional)

query

string

A list of tags to filter the list result by. Resources that match any tag in this list will be excluded. Tags in query must be separated by comma.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

security_groups

body

array

A list of security_group objects.

id

body

string

The ID of the security group.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

revision_number

body

integer

The revision number of the resource.

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

security_group_rules

body

array

A list of security_group_rule objects. Refer to Security group rules for details.

tags

body

array

The list of tags on the resource.

stateful (Optional)

body

boolean

Indicates if the security group is stateful or stateless.

shared

body

boolean

Indicates whether this security group is shared to the requestor’s project.

Response Example

{
    "security_groups": [
        {
            "description": "default",
            "id": "85cc3048-abc3-43cc-89b3-377341426ac5",
            "name": "default",
            "security_group_rules": [
                {
                    "direction": "egress",
                    "ethertype": "IPv6",
                    "id": "3c0e45ff-adaf-4124-b083-bf390e5482ff",
                    "port_range_max": null,
                    "port_range_min": null,
                    "protocol": null,
                    "remote_group_id": null,
                    "remote_ip_prefix": null,
                    "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
                    "project_id": "e4f50856753b4dc6afee5fa6b9b6c550",
                    "revision_number": 1,
                    "tags": ["tag1,tag2"],
                    "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550",
                    "created_at": "2018-03-19T19:16:56Z",
                    "updated_at": "2018-03-19T19:16:56Z",
                    "description": "",
                    "belongs_to_default_sg": false
                },
                {
                    "direction": "egress",
                    "ethertype": "IPv4",
                    "id": "93aa42e5-80db-4581-9391-3a608bd0e448",
                    "port_range_max": null,
                    "port_range_min": null,
                    "protocol": null,
                    "remote_group_id": null,
                    "remote_ip_prefix": null,
                    "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
                    "project_id": "e4f50856753b4dc6afee5fa6b9b6c550",
                    "revision_number": 2,
                    "tags": ["tag1,tag2"],
                    "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550",
                    "created_at": "2018-03-19T19:16:56Z",
                    "updated_at": "2018-03-19T19:16:56Z",
                    "description": "",
                    "belongs_to_default_sg": false
                },
                {
                    "direction": "ingress",
                    "ethertype": "IPv6",
                    "id": "c0b09f00-1d49-4e64-a0a7-8a186d928138",
                    "port_range_max": null,
                    "port_range_min": null,
                    "protocol": null,
                    "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
                    "remote_ip_prefix": null,
                    "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
                    "project_id": "e4f50856753b4dc6afee5fa6b9b6c550",
                    "revision_number": 1,
                    "tags": ["tag1,tag2"],
                    "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550",
                    "created_at": "2018-03-19T19:16:56Z",
                    "updated_at": "2018-03-19T19:16:56Z",
                    "description": "",
                    "belongs_to_default_sg": false
                },
                {
                    "direction": "ingress",
                    "ethertype": "IPv4",
                    "id": "f7d45c89-008e-4bab-88ad-d6811724c51c",
                    "port_range_max": null,
                    "port_range_min": null,
                    "protocol": null,
                    "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
                    "remote_ip_prefix": null,
                    "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
                    "project_id": "e4f50856753b4dc6afee5fa6b9b6c550",
                    "revision_number": 1,
                    "tags": ["tag1,tag2"],
                    "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550",
                    "created_at": "2018-03-19T19:16:56Z",
                    "updated_at": "2018-03-19T19:16:56Z",
                    "description": "",
                    "belongs_to_default_sg": false
                }
            ],
            "project_id": "e4f50856753b4dc6afee5fa6b9b6c550",
            "revision_number": 8,
            "created_at": "2018-03-19T19:16:56Z",
            "updated_at": "2018-03-19T19:16:56Z",
            "tags": ["tag1,tag2"],
            "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550",
            "stateful": true,
            "shared": false
        }
    ]
}
POST
/v2.0/security-groups

Create security group

Creates an OpenStack Networking security group.

This operation creates a security group with default security group rules for the IPv4 and IPv6 ether types.

Normal response codes: 201

Error response codes: 400, 401, 409

Request

Name

In

Type

Description

security_group

body

object

A security_group object.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

name

body

string

Human-readable name of the resource.

stateful (Optional)

body

boolean

Indicates if the security group is stateful or stateless.

Request Example

{
    "security_group": {
        "name": "new-webservers",
        "description": "security group for webservers",
        "stateful": true
    }
}

Response Parameters

Name

In

Type

Description

security_group

body

object

A security_group object.

id

body

string

The ID of the security group.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

revision_number

body

integer

The revision number of the resource.

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

security_group_rules

body

array

A list of security_group_rule objects. Refer to Security group rules for details.

tags

body

array

The list of tags on the resource.

stateful (Optional)

body

boolean

Indicates if the security group is stateful or stateless.

shared

body

boolean

Indicates whether this security group is shared to the requestor’s project.

Response Example

{
    "security_group": {
        "description": "security group for webservers",
        "id": "2076db17-a522-4506-91de-c6dd8e837028",
        "name": "new-webservers",
        "security_group_rules": [
            {
                "direction": "egress",
                "ethertype": "IPv4",
                "id": "38ce2d8e-e8f1-48bd-83c2-d33cb9f50c3d",
                "port_range_max": null,
                "port_range_min": null,
                "protocol": null,
                "remote_group_id": null,
                "remote_ip_prefix": null,
                "security_group_id": "2076db17-a522-4506-91de-c6dd8e837028",
                "project_id": "e4f50856753b4dc6afee5fa6b9b6c550",
                "created_at": "2018-03-19T19:16:56Z",
                "updated_at": "2018-03-19T19:16:56Z",
                "revision_number": 1,
                "revisio[n_number": 1,
                "tags": ["tag1,tag2"],
                "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550",
                "description": "",
                "belongs_to_default_sg": false
            },
            {
                "direction": "egress",
                "ethertype": "IPv6",
                "id": "565b9502-12de-4ffd-91e9-68885cff6ae1",
                "port_range_max": null,
                "port_range_min": null,
                "protocol": null,
                "remote_group_id": null,
                "remote_ip_prefix": null,
                "security_group_id": "2076db17-a522-4506-91de-c6dd8e837028",
                "project_id": "e4f50856753b4dc6afee5fa6b9b6c550",
                "created_at": "2018-03-19T19:16:56Z",
                "updated_at": "2018-03-19T19:16:56Z",
                "revision_number": 1,
                "tags": ["tag1,tag2"],
                "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550",
                "description": "",
                "belongs_to_default_sg": false
            }
        ],
        "project_id": "e4f50856753b4dc6afee5fa6b9b6c550",
        "created_at": "2018-03-19T19:16:56Z",
        "updated_at": "2018-03-19T19:16:56Z",
        "revision_number": 1,
        "tags": ["tag1,tag2"],
        "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550",
        "stateful": true,
        "shared": false
    }
}
GET
/v2.0/security-groups/{security_group_id}

Show security group

Shows details for a security group.

The associated security group rules are contained in the response.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

security_group_id

path

string

The ID of the security group.

verbose (Optional)

query

boolean

Show detailed information.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Request Example

GET /v2.0/security-groups/85cc3048-abc3-43cc-89b3-377341426ac5
Accept: application/json

Response Parameters

Name

In

Type

Description

security_group

body

object

A security_group object.

id

body

string

The ID of the security group.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

revision_number

body

integer

The revision number of the resource.

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

security_group_rules

body

array

A list of security_group_rule objects. Refer to Security group rules for details.

tags

body

array

The list of tags on the resource.

stateful (Optional)

body

boolean

Indicates if the security group is stateful or stateless.

shared

body

boolean

Indicates whether this security group is shared to the requestor’s project.

Response Example

{
    "security_group": {
        "description": "default",
        "id": "85cc3048-abc3-43cc-89b3-377341426ac5",
        "name": "default",
        "security_group_rules": [
            {
                "direction": "egress",
                "ethertype": "IPv6",
                "id": "3c0e45ff-adaf-4124-b083-bf390e5482ff",
                "port_range_max": null,
                "port_range_min": null,
                "protocol": null,
                "remote_group_id": null,
                "remote_ip_prefix": null,
                "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
                "project_id": "e4f50856753b4dc6afee5fa6b9b6c550",
                "revision_number": 1,
                "tags": ["tag1,tag2"],
                "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550",
                "created_at": "2018-03-19T19:16:56Z",
                "updated_at": "2018-03-19T19:16:56Z",
                "description": "",
                "belongs_to_default_sg": false
            },
            {
                "direction": "egress",
                "ethertype": "IPv4",
                "id": "93aa42e5-80db-4581-9391-3a608bd0e448",
                "port_range_max": null,
                "port_range_min": null,
                "protocol": null,
                "remote_group_id": null,
                "remote_ip_prefix": null,
                "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
                "project_id": "e4f50856753b4dc6afee5fa6b9b6c550",
                "revision_number": 2,
                "tags": ["tag1,tag2"],
                "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550",
                "created_at": "2018-03-19T19:16:56Z",
                "updated_at": "2018-03-19T19:16:56Z",
                "description": "",
                "belongs_to_default_sg": false
            },
            {
                "direction": "ingress",
                "ethertype": "IPv6",
                "id": "c0b09f00-1d49-4e64-a0a7-8a186d928138",
                "port_range_max": null,
                "port_range_min": null,
                "protocol": null,
                "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
                "remote_ip_prefix": null,
                "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
                "project_id": "e4f50856753b4dc6afee5fa6b9b6c550",
                "revision_number": 1,
                "tags": ["tag1,tag2"],
                "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550",
                "created_at": "2018-03-19T19:16:56Z",
                "updated_at": "2018-03-19T19:16:56Z",
                "description": "",
                "belongs_to_default_sg": false
            },
            {
                "direction": "ingress",
                "ethertype": "IPv4",
                "id": "f7d45c89-008e-4bab-88ad-d6811724c51c",
                "port_range_max": null,
                "port_range_min": null,
                "protocol": null,
                "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
                "remote_ip_prefix": null,
                "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
                "project_id": "e4f50856753b4dc6afee5fa6b9b6c550",
                "revision_number": 1,
                "tags": ["tag1,tag2"],
                "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550",
                "created_at": "2018-03-19T19:16:56Z",
                "updated_at": "2018-03-19T19:16:56Z",
                "description": "",
                "belongs_to_default_sg": false
            }
        ],
        "project_id": "e4f50856753b4dc6afee5fa6b9b6c550",
        "created_at": "2018-03-19T19:16:56Z",
        "updated_at": "2018-03-19T19:16:56Z",
        "revision_number": 4,
        "tags": ["tag1,tag2"],
        "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550",
        "stateful": true,
        "shared": false
    }
}
PUT
/v2.0/security-groups/{security_group_id}

Update security group

Updates a security group.

Normal response codes: 200

Error response codes: 400, 401, 403, 404, 412

Request

Name

In

Type

Description

security_group_id

path

string

The ID of the security group.

security_group

body

object

A security_group object.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

name

body

string

Human-readable name of the resource.

Request Example

{
    "security_group": {
        "name": "mysecgroup",
        "description": "my security group",
        "stateful": true
    }
}

Response Parameters

Name

In

Type

Description

security_group

body

object

A security_group object.

id

body

string

The ID of the security group.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

revision_number

body

integer

The revision number of the resource.

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

security_group_rules

body

array

A list of security_group_rule objects. Refer to Security group rules for details.

tags

body

array

The list of tags on the resource.

stateful (Optional)

body

boolean

Indicates if the security group is stateful or stateless.

shared

body

boolean

Indicates whether this security group is shared to the requestor’s project.

Response Example

{
    "security_group": {
        "security_group_rules": [],
        "project_id": "a52cdb9cc7854a39a23d3af73a40899e",
        "revision_number": 4,
        "tenant_id": "a52cdb9cc7854a39a23d3af73a40899e",
        "created_at": "2018-03-19T19:16:56Z",
        "updated_at": "2018-03-19T19:16:56Z",
        "id": "01fbade5-b664-42f6-83ae-4e214f4263fa",
        "name": "mysecgroup",
        "description": "my security group",
        "tags": ["tag1,tag2"],
        "stateful": true,
        "shared": false,
        "belongs_to_default_sg": false
    }
}
DELETE
/v2.0/security-groups/{security_group_id}

Delete security group

Deletes an OpenStack Networking security group.

This operation deletes an OpenStack Networking security group and its associated security group rules, provided that a port is not associated with the security group. If a port is associated with the security group 409 (Conflict) is returned.

This operation does not require a request body. This operation does not return a response body.

Normal response codes: 204

Error response codes: 401, 404, 409, 412

Request

Name

In

Type

Description

security_group_id

path

string

The ID of the security group.

Request Example

DELETE /v2.0/security-groups/e470bdfc-4869-459b-a561-cb3377efae59
Content-Type: application/json
Accept: application/json

Response

There is no body content for the response of a successful DELETE request.

Security group default rules (security-group-default-rules)

Lists, creates, shows information for, and deletes security group default rules.

GET
/v2.0/default-security-group-rules

List security group default rules

Lists a summary of all OpenStack Networking security group rules that are used for every newly created Security Group.

The list provides the ID for each security group default rule.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

remote_group_id (Optional)

query

string

Filter the security group rule list result by the ID of the remote group that associates with this security group rule. This field can contains uuid of the security group or special word PARENT which means that in the real rule created from this template, uuid of the owner Security Group will be put as remote_group_id.

direction (Optional)

query

string

Filter the security group rule list result by the direction in which the security group rule is applied, which is ingress or egress.

protocol (Optional)

query

string

Filter the security group rule list result by the IP protocol.

ethertype (Optional)

query

string

Filter the security group rule list result by the ethertype of network traffic. The value must be IPv4 or IPv6.

port_range_max (Optional)

query

integer

Filter the security group rule list result by the maximum port number in the range that is matched by the security group rule.

port_range_min (Optional)

query

integer

Filter the security group rule list result by the minimum port number in the range that is matched by the security group rule.

remote_ip_prefix (Optional)

query

string

Filter the list result by the remote IP prefix that is matched by this security group rule.

remote_address_group_id (Optional)

query

string

Filter the security group rule list result by the ID of the remote address group that associates with this security group rule.

used_in_default_sg (Optional)

body

boolean

Fiter by security group rule templates which should be used in default security group created automatically for each new project.

used_in_non_default_sg (Optional)

body

boolean

Fiter by security group rule templates which should be used in custom security groups created by project users.

id (Optional)

query

string

Filter the list result by the ID of the resource.

description (Optional)

query

string

Filter the list result by the human-readable description of the resource.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a security group rule attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • direction

  • ethertype

  • id

  • port_range_max

  • port_range_min

  • protocol

  • remote_group_id

  • remote_ip_prefix

  • security_group_id

  • tenant_id

  • project_id

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

security_group_rules

body

array

A list of security_group_rule objects. Refer to Security group rules for details.

remote_group_id (Optional)

query

string

Filter the security group rule list result by the ID of the remote group that associates with this security group rule. This field can contains uuid of the security group or special word PARENT which means that in the real rule created from this template, uuid of the owner Security Group will be put as remote_group_id.

direction

body

string

Ingress or egress, which is the direction in which the security group rule is applied.

protocol

body

string

The IP protocol can be represented by a string, an integer, or null. Valid string or integer values are any or 0, ah or 51, dccp or 33, egp or 8, esp or 50, gre or 47, icmp or 1, icmpv6 or 58, igmp or 2, ipip or 4, ipv6-encap or 41, ipv6-frag or 44, ipv6-icmp or 58, ipv6-nonxt or 59, ipv6-opts or 60, ipv6-route or 43, ospf or 89, pgm or 113, rsvp or 46, sctp or 132, tcp or 6, udp or 17, udplite or 136, vrrp or 112. Additionally, any integer value between [0-255] is also valid. The string any (or integer 0) means all IP protocols. See the constants in neutron_lib.constants for the most up-to-date list of supported strings.

ethertype

body

string

Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.

port_range_max

body

integer

The maximum port number in the range that is matched by the security group rule. If the protocol is TCP, UDP, DCCP, SCTP or UDP-Lite this value must be greater than or equal to the port_range_min attribute value. If the protocol is ICMP, this value must be an ICMP code.

port_range_min

body

integer

The minimum port number in the range that is matched by the security group rule. If the protocol is TCP, UDP, DCCP, SCTP or UDP-Lite this value must be less than or equal to the port_range_max attribute value. If the protocol is ICMP, this value must be an ICMP type.

remote_ip_prefix

body

string

The remote IP prefix that is matched by this security group rule.

remote_address_group_id

body

string

The remote address group UUID to associate with this security group rule.

used_in_default_sg (Optional)

body

boolean

Whether this security group rule template should be used in default security group created automatically for each new project. Default value is False.

used_in_non_default_sg (Optional)

body

boolean

Whether this security group rule template should be used in custom security groups created by project user. Default value is True.

id

body

string

The ID of the security group default rule.

description

body

string

A human-readable description for the resource.

Response Example

{
    "default_security_group_rules": [
        {
            "direction": "egress",
            "ethertype": "IPv6",
            "id": "3c0e45ff-adaf-4124-b083-bf390e5482ff",
            "port_range_max": null,
            "port_range_min": null,
            "protocol": null,
            "remote_group_id": null,
            "remote_ip_prefix": null,
            "remote_address_group_id": null,
            "used_in_default_sg": true,
            "used_in_default_non_sg": true,
            "description": ""
        },
        {
            "direction": "egress",
            "ethertype": "IPv4",
            "id": "93aa42e5-80db-4581-9391-3a608bd0e448",
            "port_range_max": null,
            "port_range_min": null,
            "protocol": null,
            "remote_group_id": null,
            "remote_ip_prefix": null,
            "remote_address_group_id": null,
            "used_in_default_sg": true,
            "used_in_default_non_sg": true,
            "description": ""
        },
        {
            "direction": "ingress",
            "ethertype": "IPv6",
            "id": "333e64bf-cab0-47ed-8303-fca711b74433",
            "port_range_max": null,
            "port_range_min": null,
            "protocol": null,
            "remote_group_id": "PARENT",
            "remote_ip_prefix": null,
            "remote_address_group_id": null,
            "used_in_default_sg": true,
            "used_in_default_non_sg": true,
            "description": ""
        },
        {
            "direction": "ingress",
            "ethertype": "IPv4",
            "id": "91eff177-4e20-4407-a7ac-843c625316e3",
            "port_range_max": null,
            "port_range_min": null,
            "protocol": null,
            "remote_group_id": "PARENT",
            "remote_ip_prefix": null,
            "remote_address_group_id": null,
            "used_in_default_sg": true,
            "used_in_default_non_sg": true,
            "description": ""
        },
        {
            "direction": "ingress",
            "ethertype": "IPv6",
            "id": "d41fc3d7-46bc-405e-a4f6-029cbb63c5c4",
            "port_range_max": 22,
            "port_range_min": 22,
            "protocol": null,
            "remote_group_id": null,
            "remote_ip_prefix": null,
            "remote_address_group_id": null,
            "used_in_default_sg": false,
            "used_in_default_non_sg": true,
            "description": "Allow SSH connections over IPv6"
        },
        {
            "direction": "ingress",
            "ethertype": "IPv4",
            "id": "03315f60-52dd-40e0-a769-04360cb3e6c1",
            "port_range_max": 22,
            "port_range_min": 22,
            "protocol": null,
            "remote_group_id": null,
            "remote_ip_prefix": null,
            "remote_address_group_id": null,
            "used_in_default_sg": false,
            "used_in_default_non_sg": true,
            "description": "Allow SSH connections over IPv4"
        }
    ]
}
POST
/v2.0/default-security-group-rules

Create security group default rule

Creates an Openstack Networking security group rule template.

Normal response codes: 201

Error response codes: 400, 401, 404, 409

Request

Name

In

Type

Description

default_security_group_rule

body

object

A default_security_group_rule object.

remote_group_id (Optional)

body

string

The remote group UUID to associate with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body.

direction

body

string

Ingress or egress, which is the direction in which the security group rule is applied.

protocol (Optional)

body

string

The IP protocol can be represented by a string, an integer, or null. Valid string or integer values are any or 0, ah or 51, dccp or 33, egp or 8, esp or 50, gre or 47, icmp or 1, icmpv6 or 58, igmp or 2, ipip or 4, ipv6-encap or 41, ipv6-frag or 44, ipv6-icmp or 58, ipv6-nonxt or 59, ipv6-opts or 60, ipv6-route or 43, ospf or 89, pgm or 113, rsvp or 46, sctp or 132, tcp or 6, udp or 17, udplite or 136, vrrp or 112. Additionally, any integer value between [0-255] is also valid. The string any (or integer 0) means all IP protocols. See the constants in neutron_lib.constants for the most up-to-date list of supported strings.

ethertype (Optional)

body

string

Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.

port_range_max (Optional)

body

integer

The maximum port number in the range that is matched by the security group rule. If the protocol is TCP, UDP, DCCP, SCTP or UDP-Lite this value must be greater than or equal to the port_range_min attribute value. If the protocol is ICMP, this value must be an ICMP code.

port_range_min (Optional)

body

integer

The minimum port number in the range that is matched by the security group rule. If the protocol is TCP, UDP, DCCP, SCTP or UDP-Lite this value must be less than or equal to the port_range_max attribute value. If the protocol is ICMP, this value must be an ICMP type.

remote_ip_prefix (Optional)

body

string

The remote IP prefix that is matched by this security group rule.

remote_address_group_id (Optional)

query

string

UUID of the remote address group that associates with the security group rule created from this template.

used_in_default_sg (Optional)

body

boolean

Whether this security group rule template should be used in default security group created automatically for each new project. Default value is False.

used_in_non_default_sg (Optional)

body

boolean

Whether this security group rule template should be used in custom security groups created by project user. Default value is True.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

Request Example

{
    "default_security_group_rule": {
        "direction": "ingress",
        "port_range_min": "80",
        "ethertype": "IPv4",
        "port_range_max": "80",
        "protocol": "tcp"
    }
}

Response Parameters

Name

In

Type

Description

remote_group_id

body

string

The remote group UUID to associate with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body.

direction

body

string

Ingress or egress, which is the direction in which the security group rule is applied.

protocol

body

string

The IP protocol can be represented by a string, an integer, or null. Valid string or integer values are any or 0, ah or 51, dccp or 33, egp or 8, esp or 50, gre or 47, icmp or 1, icmpv6 or 58, igmp or 2, ipip or 4, ipv6-encap or 41, ipv6-frag or 44, ipv6-icmp or 58, ipv6-nonxt or 59, ipv6-opts or 60, ipv6-route or 43, ospf or 89, pgm or 113, rsvp or 46, sctp or 132, tcp or 6, udp or 17, udplite or 136, vrrp or 112. Additionally, any integer value between [0-255] is also valid. The string any (or integer 0) means all IP protocols. See the constants in neutron_lib.constants for the most up-to-date list of supported strings.

ethertype

body

string

Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.

port_range_max

body

integer

The maximum port number in the range that is matched by the security group rule. If the protocol is TCP, UDP, DCCP, SCTP or UDP-Lite this value must be greater than or equal to the port_range_min attribute value. If the protocol is ICMP, this value must be an ICMP code.

port_range_min

body

integer

The minimum port number in the range that is matched by the security group rule. If the protocol is TCP, UDP, DCCP, SCTP or UDP-Lite this value must be less than or equal to the port_range_max attribute value. If the protocol is ICMP, this value must be an ICMP type.

remote_ip_prefix

body

string

The remote IP prefix that is matched by this security group rule.

remote_address_group_id

body

string

The remote address group UUID to associate with this security group rule.

used_in_default_sg (Optional)

body

boolean

Whether this security group rule template should be used in default security group created automatically for each new project. Default value is False.

used_in_non_default_sg (Optional)

body

boolean

Whether this security group rule template should be used in custom security groups created by project user. Default value is True.

id

body

string

The ID of the security group default rule.

description

body

string

A human-readable description for the resource.

Response Example

{
    "default_security_group_rule": {
        "direction": "ingress",
        "ethertype": "IPv4",
        "id": "2bc0accf-312e-429a-956e-e4407625eb62",
        "port_range_max": 80,
        "port_range_min": 80,
        "protocol": "tcp",
        "remote_group_id": null,
        "remote_ip_prefix": null,
        "remote_address_group_id": null,
        "used_in_default_sg": false,
        "used_in_non_default_sg": true,
        "description": ""
    }
}

Warning

The security group rule template APIs do not validate the UUID of the resources like remote address group id or remote group ID. Any string can be provided here, but please note that it will be used to create real security group rules for projects, and if the UUID of a non-existing security group or remote address group is used, it will cause errors during creation of the security groups.

GET
/v2.0/default-security-group-rules/{default_security_group_rule_id}

Show security group default rule

Shows detailed information for a security group default rule.

The response body contains the following information about the security group rule:

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

default_security_group_rule_id

path

string

The ID of the security group default rule.

verbose (Optional)

query

boolean

Show detailed information.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

default_security_group_rule

body

object

A default_security_group_rule object.

remote_group_id

body

string

The remote group UUID to associate with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body.

direction

body

string

Ingress or egress, which is the direction in which the security group rule is applied.

protocol

body

string

The IP protocol can be represented by a string, an integer, or null. Valid string or integer values are any or 0, ah or 51, dccp or 33, egp or 8, esp or 50, gre or 47, icmp or 1, icmpv6 or 58, igmp or 2, ipip or 4, ipv6-encap or 41, ipv6-frag or 44, ipv6-icmp or 58, ipv6-nonxt or 59, ipv6-opts or 60, ipv6-route or 43, ospf or 89, pgm or 113, rsvp or 46, sctp or 132, tcp or 6, udp or 17, udplite or 136, vrrp or 112. Additionally, any integer value between [0-255] is also valid. The string any (or integer 0) means all IP protocols. See the constants in neutron_lib.constants for the most up-to-date list of supported strings.

ethertype

body

string

Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.

port_range_max

body

integer

The maximum port number in the range that is matched by the security group rule. If the protocol is TCP, UDP, DCCP, SCTP or UDP-Lite this value must be greater than or equal to the port_range_min attribute value. If the protocol is ICMP, this value must be an ICMP code.

port_range_min

body

integer

The minimum port number in the range that is matched by the security group rule. If the protocol is TCP, UDP, DCCP, SCTP or UDP-Lite this value must be less than or equal to the port_range_max attribute value. If the protocol is ICMP, this value must be an ICMP type.

remote_ip_prefix

body

string

The remote IP prefix that is matched by this security group rule.

remote_address_group_id

body

string

The remote address group UUID to associate with this security group rule.

used_in_default_sg (Optional)

body

boolean

Whether this security group rule template should be used in default security group created automatically for each new project. Default value is False.

used_in_non_default_sg (Optional)

body

boolean

Whether this security group rule template should be used in custom security groups created by project user. Default value is True.

id

body

string

The ID of the security group default rule.

description

body

string

A human-readable description for the resource.

Response Example

{
    "default_security_group_rule": {
        "direction": "ingress",
        "ethertype": "IPv4",
        "id": "2bc0accf-312e-429a-956e-e4407625eb62",
        "port_range_max": 80,
        "port_range_min": 80,
        "protocol": "tcp",
        "remote_group_id": null,
        "remote_ip_prefix": null,
        "remote_address_group_id": null,
        "used_in_default_sg": false,
        "used_in_non_default_sg": true,
        "description": ""
    }
}
DELETE
/v2.0/default-security-group-rules/{default_security_group_rule_id}

Delete security group default rule

Deletes an OpenStack Networking security group rule template.

Normal response codes: 204

Error response codes: 401, 404, 412

Request

Name

In

Type

Description

default_security_group_rule_id

path

string

The ID of the security group default rule.

Response

There is no body content is returned on a successful DELETE request.

VPNaaS 2.0 (vpn, vpnservices, ikepolicies, ipsecpolicies, endpoint-groups, ipsec-site-connections)

The Virtual-Private-Network-as-a-Service (VPNaaS) extension enables OpenStack projects to extend private networks across the public telecommunication infrastructure.

This initial implementation of the VPNaaS extension provides:

  • Site-to-site VPN that connects two private networks.

  • Multiple VPN connections per project.

  • IKEv1 policy support with 3des, aes-128, aes-256, or aes-192 encryption.

  • IPsec policy support with 3des, aes-128, aes-192, or aes-256 encryption, sha1 authentication, ESP, AH, or AH-ESP transform protocol, and tunnel or transport mode encapsulation.

  • Dead Peer Detection (DPD) with hold, clear, restart, disabled, or restart-by-peer actions.

This extension introduces these resources:

  • service. A parent object that associates VPN with a specific subnet and router.

  • ikepolicy. The Internet Key Exchange (IKE) policy that identifies the authentication and encryption algorithm to use during phase one and two negotiation of a VPN connection.

  • ipsecpolicy. The IP security policy that specifies the authentication and encryption algorithm and encapsulation mode to use for the established VPN connection.

  • ipsec-site-connection. Details for the site-to-site IPsec connection, including the peer CIDRs, MTU, authentication mode, peer address, DPD settings, and status.

VPN Endpoint Groups

The endpoint-groups extension adds support for defining one or more endpoints of a specific type, and can be used to specify both local and peer endpoints for IPsec connections.

VPN Flavors

The vpn-flavors extension adds the flavor_id attribute to vpnservices resources. During vpnservice creation, if a flavor_id is passed, it is used to find the provider for the driver which would handle the newly created vpnservice.

GET
/v2.0/vpn/ikepolicies

List IKE policies

Lists IKE policies.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401, 403

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

ikepolicies

body

array

A list of ikepolicy objects.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

auth_algorithm (Optional)

body

string

The authentication hash algorithm. Valid values are sha1, sha256, sha384, sha512, aes-xcbc, aes-cmac. The default is sha1.

encryption_algorithm (Optional)

body

string

The encryption algorithm. A valid value is 3des, aes-128, aes-192, aes-256. Additional values for AES CCM and GCM modes are defined (e.g. aes-256-ccm-16, aes-256-gcm-16) for all combinations of key length 128, 192, 256 bits and ICV length 8, 12, 16 octets. Default is aes-128.

pfs (Optional)

body

string

Perfect forward secrecy (PFS). A valid value is Group2, Group5, Group14 to Group31. Default is Group5.

value (Optional)

body

integer

The lifetime value, as a positive integer. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

phase1_negotiation_mode (Optional)

body

string

The IKE mode. A valid value is main, which is the default.

units (Optional)

body

string

The units for the lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

lifetime (Optional)

body

object

The lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

id

body

string

The ID of the IKE policy.

ike_version (Optional)

body

string

The IKE version. A valid value is v1 or v2. Default is v1.

Response Example

{
    "ikepolicies": [
        {
            "name": "ikepolicy1",
            "project_id": "ccb81365fe36411a9011e90491fe1330",
            "tenant_id": "ccb81365fe36411a9011e90491fe1330",
            "auth_algorithm": "sha1",
            "encryption_algorithm": "aes-256",
            "pfs": "group5",
            "phase1_negotiation_mode": "main",
            "lifetime": {
                "units": "seconds",
                "value": 3600
            },
            "ike_version": "v1",
            "id": "5522aff7-1b3c-48dd-9c3c-b50f016b73db",
            "description": ""
        }
    ]
}
POST
/v2.0/vpn/ikepolicies

Create IKE policy

Creates an IKE policy.

The IKE policy is used for phases one and two negotiation of the VPN connection. You can specify both the authentication and encryption algorithms for connections.

Normal response codes: 201

Error response codes: 400, 401

Request

Name

In

Type

Description

ikepolicy

body

object

An ikepolicy object.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

auth_algorithm (Optional)

body

string

The authentication hash algorithm. Valid values are sha1, sha256, sha384, sha512, aes-xcbc, aes-cmac. The default is sha1.

encryption_algorithm (Optional)

body

string

The encryption algorithm. A valid value is 3des, aes-128, aes-192, aes-256. Additional values for AES CCM and GCM modes are defined (e.g. aes-256-ccm-16, aes-256-gcm-16) for all combinations of key length 128, 192, 256 bits and ICV length 8, 12, 16 octets. Default is aes-128.

pfs (Optional)

body

string

Perfect forward secrecy (PFS). A valid value is Group2, Group5, Group14 to Group31. Default is Group5.

value (Optional)

body

integer

The lifetime value, as a positive integer. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

phase1_negotiation_mode (Optional)

body

string

The IKE mode. A valid value is main, which is the default.

units (Optional)

body

string

The units for the lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

lifetime (Optional)

body

object

The lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

ike_version (Optional)

body

string

The IKE version. A valid value is v1 or v2. Default is v1.

Request Example

{
    "ikepolicy": {
        "phase1_negotiation_mode": "main",
        "auth_algorithm": "sha1",
        "encryption_algorithm": "aes-128",
        "pfs": "group5",
        "lifetime": {
            "units": "seconds",
            "value": 7200
        },
        "ike_version": "v1",
        "name": "ikepolicy1"
    }
}

Response Parameters

Name

In

Type

Description

ikepolicies

body

array

A list of ikepolicy objects.

ikepolicy

body

object

An ikepolicy object.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

auth_algorithm (Optional)

body

string

The authentication hash algorithm. Valid values are sha1, sha256, sha384, sha512, aes-xcbc, aes-cmac. The default is sha1.

encryption_algorithm (Optional)

body

string

The encryption algorithm. A valid value is 3des, aes-128, aes-192, aes-256. Additional values for AES CCM and GCM modes are defined (e.g. aes-256-ccm-16, aes-256-gcm-16) for all combinations of key length 128, 192, 256 bits and ICV length 8, 12, 16 octets. Default is aes-128.

pfs (Optional)

body

string

Perfect forward secrecy (PFS). A valid value is Group2, Group5, Group14 to Group31. Default is Group5.

value (Optional)

body

integer

The lifetime value, as a positive integer. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

phase1_negotiation_mode (Optional)

body

string

The IKE mode. A valid value is main, which is the default.

units (Optional)

body

string

The units for the lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

lifetime (Optional)

body

object

The lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

id

body

string

The ID of the IKE policy.

ike_version (Optional)

body

string

The IKE version. A valid value is v1 or v2. Default is v1.

Response Example

{
    "ikepolicy": {
        "name": "ikepolicy1",
        "project_id": "ccb81365fe36411a9011e90491fe1330",
        "tenant_id": "ccb81365fe36411a9011e90491fe1330",
        "auth_algorithm": "sha1",
        "encryption_algorithm": "aes-128",
        "pfs": "group5",
        "phase1_negotiation_mode": "main",
        "lifetime": {
            "units": "seconds",
            "value": 7200
        },
        "ike_version": "v1",
        "id": "5522aff7-1b3c-48dd-9c3c-b50f016b73db",
        "description": ""
    }
}
GET
/v2.0/vpn/ikepolicies/{ikepolicy_id}

Show IKE policy details

Shows details for an IKE policy.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 403, 404

Request

Name

In

Type

Description

ikepolicy_id

path

string

The ID of the IKE policy.

Response Parameters

Name

In

Type

Description

ikepolicies

body

array

A list of ikepolicy objects.

ikepolicy

body

object

An ikepolicy object.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

auth_algorithm (Optional)

body

string

The authentication hash algorithm. Valid values are sha1, sha256, sha384, sha512, aes-xcbc, aes-cmac. The default is sha1.

encryption_algorithm (Optional)

body

string

The encryption algorithm. A valid value is 3des, aes-128, aes-192, aes-256. Additional values for AES CCM and GCM modes are defined (e.g. aes-256-ccm-16, aes-256-gcm-16) for all combinations of key length 128, 192, 256 bits and ICV length 8, 12, 16 octets. Default is aes-128.

pfs (Optional)

body

string

Perfect forward secrecy (PFS). A valid value is Group2, Group5, Group14 to Group31. Default is Group5.

value (Optional)

body

integer

The lifetime value, as a positive integer. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

phase1_negotiation_mode (Optional)

body

string

The IKE mode. A valid value is main, which is the default.

units (Optional)

body

string

The units for the lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

lifetime (Optional)

body

object

The lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

id

body

string

The ID of the IKE policy.

ike_version (Optional)

body

string

The IKE version. A valid value is v1 or v2. Default is v1.

Response Example

{
    "ikepolicy": {
        "name": "ikepolicy1",
        "project_id": "ccb81365fe36411a9011e90491fe1330",
        "tenant_id": "ccb81365fe36411a9011e90491fe1330",
        "auth_algorithm": "sha1",
        "encryption_algorithm": "aes-256",
        "pfs": "group5",
        "phase1_negotiation_mode": "main",
        "lifetime": {
            "units": "seconds",
            "value": 3600
        },
        "ike_version": "v1",
        "id": "5522aff7-1b3c-48dd-9c3c-b50f016b73db",
        "description": ""
    }
}
PUT
/v2.0/vpn/ikepolicies/{ikepolicy_id}

Update IKE policy

Updates policy settings in an IKE policy.

Normal response codes: 200

Error response codes: 400, 401, 404

Request

Name

In

Type

Description

ikepolicy_id

path

string

The ID of the IKE policy.

ikepolicy

body

object

An ikepolicy object.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

auth_algorithm (Optional)

body

string

The authentication hash algorithm. Valid values are sha1, sha256, sha384, sha512, aes-xcbc, aes-cmac. The default is sha1.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

encryption_algorithm (Optional)

body

string

The encryption algorithm. A valid value is 3des, aes-128, aes-192, aes-256. Additional values for AES CCM and GCM modes are defined (e.g. aes-256-ccm-16, aes-256-gcm-16) for all combinations of key length 128, 192, 256 bits and ICV length 8, 12, 16 octets. Default is aes-128.

pfs (Optional)

body

string

Perfect forward secrecy (PFS). A valid value is Group2, Group5, Group14 to Group31. Default is Group5.

value (Optional)

body

integer

The lifetime value, as a positive integer. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

phase1_negotiation_mode (Optional)

body

string

The IKE mode. A valid value is main, which is the default.

units (Optional)

body

string

The units for the lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

lifetime (Optional)

body

object

The lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

ike_version (Optional)

body

string

The IKE version. A valid value is v1 or v2. Default is v1.

Request Example

{
    "ikepolicy": {
        "encryption_algorithm": "aes-256"
    }
}

Response Parameters

Name

In

Type

Description

ikepolicies

body

array

A list of ikepolicy objects.

ikepolicy

body

object

An ikepolicy object.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

auth_algorithm (Optional)

body

string

The authentication hash algorithm. Valid values are sha1, sha256, sha384, sha512, aes-xcbc, aes-cmac. The default is sha1.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

encryption_algorithm (Optional)

body

string

The encryption algorithm. A valid value is 3des, aes-128, aes-192, aes-256. Additional values for AES CCM and GCM modes are defined (e.g. aes-256-ccm-16, aes-256-gcm-16) for all combinations of key length 128, 192, 256 bits and ICV length 8, 12, 16 octets. Default is aes-128.

pfs (Optional)

body

string

Perfect forward secrecy (PFS). A valid value is Group2, Group5, Group14 to Group31. Default is Group5.

value (Optional)

body

integer

The lifetime value, as a positive integer. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

phase1_negotiation_mode (Optional)

body

string

The IKE mode. A valid value is main, which is the default.

units (Optional)

body

string

The units for the lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

lifetime (Optional)

body

object

The lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

id

body

string

The ID of the IKE policy.

ike_version (Optional)

body

string

The IKE version. A valid value is v1 or v2. Default is v1.

Response Example

{
    "ikepolicy": {
        "name": "ikepolicy1",
        "project_id": "ccb81365fe36411a9011e90491fe1330",
        "tenant_id": "ccb81365fe36411a9011e90491fe1330",
        "auth_algorithm": "sha1",
        "encryption_algorithm": "aes-256",
        "pfs": "group5",
        "phase1_negotiation_mode": "main",
        "lifetime": {
            "units": "seconds",
            "value": 3600
        },
        "ike_version": "v1",
        "id": "5522aff7-1b3c-48dd-9c3c-b50f016b73db",
        "description": ""
    }
}
DELETE
/v2.0/vpn/ikepolicies/{ikepolicy_id}

Remove IKE policy

Removes an IKE policy.

Normal response codes: 204

Error response codes: 401, 404, 409

Request

Name

In

Type

Description

ikepolicy_id

path

string

The ID of the IKE policy.

Response

There is no body content for the response of a successful DELETE request.

GET
/v2.0/vpn/ipsecpolicies

List IPsec policies

Lists all IPsec policies.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401, 403

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

ipsecpolicies

body

array

A list of ipsecpolicy objects.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

auth_algorithm (Optional)

body

string

The authentication hash algorithm. Valid values are sha1, sha256, sha384, sha512, aes-xcbc, aes-cmac. The default is sha1.

encapsulation_mode (Optional)

body

string

The encapsulation mode. A valid value is tunnel or transport. Default is tunnel.

encryption_algorithm (Optional)

body

string

The encryption algorithm. A valid value is 3des, aes-128, aes-192, aes-256. Additional values for AES CCM and GCM modes are defined (e.g. aes-256-ccm-16, aes-256-gcm-16) for all combinations of key length 128, 192, 256 bits and ICV length 8, 12, 16 octets. Default is aes-128.

pfs (Optional)

body

string

Perfect forward secrecy (PFS). A valid value is Group2, Group5, Group14 to Group31. Default is Group5.

value (Optional)

body

integer

The lifetime value, as a positive integer. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

transform_protocol (Optional)

body

string

The transform protocol. A valid value is ESP, AH, or AH- ESP. Default is ESP.

units (Optional)

body

string

The units for the lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

lifetime (Optional)

body

object

The lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

id

body

string

The ID of the IPsec policy.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

Response Example

{
    "ipsecpolicies": [
        {
            "name": "ipsecpolicy1",
            "transform_protocol": "esp",
            "auth_algorithm": "sha1",
            "encapsulation_mode": "tunnel",
            "encryption_algorithm": "aes-128",
            "pfs": "group14",
            "project_id": "ccb81365fe36411a9011e90491fe1330",
            "tenant_id": "ccb81365fe36411a9011e90491fe1330",
            "lifetime": {
                "units": "seconds",
                "value": 3600
            },
            "id": "5291b189-fd84-46e5-84bd-78f40c05d69c",
            "description": ""
        }
    ]
}
POST
/v2.0/vpn/ipsecpolicies

Create IPsec policy

Creates an IP security (IPsec) policy.

The IPsec policy specifies the authentication and encryption algorithms and encapsulation mode to use for the established VPN connection.

Normal response codes: 201

Error response codes: 400, 401

Request

Name

In

Type

Description

ipsecpolicy

body

object

An ipsecpolicy object.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

auth_algorithm (Optional)

body

string

The authentication hash algorithm. Valid values are sha1, sha256, sha384, sha512, aes-xcbc, aes-cmac. The default is sha1.

encapsulation_mode (Optional)

body

string

The encapsulation mode. A valid value is tunnel or transport. Default is tunnel.

encryption_algorithm (Optional)

body

string

The encryption algorithm. A valid value is 3des, aes-128, aes-192, aes-256. Additional values for AES CCM and GCM modes are defined (e.g. aes-256-ccm-16, aes-256-gcm-16) for all combinations of key length 128, 192, 256 bits and ICV length 8, 12, 16 octets. Default is aes-128.

pfs (Optional)

body

string

Perfect forward secrecy (PFS). A valid value is Group2, Group5, Group14 to Group31. Default is Group5.

value (Optional)

body

integer

The lifetime value, as a positive integer. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

transform_protocol (Optional)

body

string

The transform protocol. A valid value is ESP, AH, or AH- ESP. Default is ESP.

units (Optional)

body

string

The units for the lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

lifetime (Optional)

body

object

The lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

Request Example

{
    "ipsecpolicy": {
        "name": "ipsecpolicy1",
        "transform_protocol": "esp",
        "auth_algorithm": "sha1",
        "encapsulation_mode": "tunnel",
        "encryption_algorithm": "aes-128",
        "pfs": "group5",
        "lifetime": {
            "units": "seconds",
            "value": 7200
        }
    }
}

Response Parameters

Name

In

Type

Description

ipsecpolicies

body

array

A list of ipsecpolicy objects.

ipsecpolicy

body

object

An ipsecpolicy object.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

auth_algorithm (Optional)

body

string

The authentication hash algorithm. Valid values are sha1, sha256, sha384, sha512, aes-xcbc, aes-cmac. The default is sha1.

encapsulation_mode (Optional)

body

string

The encapsulation mode. A valid value is tunnel or transport. Default is tunnel.

encryption_algorithm (Optional)

body

string

The encryption algorithm. A valid value is 3des, aes-128, aes-192, aes-256. Additional values for AES CCM and GCM modes are defined (e.g. aes-256-ccm-16, aes-256-gcm-16) for all combinations of key length 128, 192, 256 bits and ICV length 8, 12, 16 octets. Default is aes-128.

pfs (Optional)

body

string

Perfect forward secrecy (PFS). A valid value is Group2, Group5, Group14 to Group31. Default is Group5.

value (Optional)

body

integer

The lifetime value, as a positive integer. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

transform_protocol (Optional)

body

string

The transform protocol. A valid value is ESP, AH, or AH- ESP. Default is ESP.

units (Optional)

body

string

The units for the lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

lifetime (Optional)

body

object

The lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

id

body

string

The ID of the IPsec policy.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

Response Example

{
    "ipsecpolicy": {
        "name": "ipsecpolicy1",
        "transform_protocol": "esp",
        "auth_algorithm": "sha1",
        "encapsulation_mode": "tunnel",
        "encryption_algorithm": "aes-128",
        "pfs": "group5",
        "project_id": "ccb81365fe36411a9011e90491fe1330",
        "tenant_id": "ccb81365fe36411a9011e90491fe1330",
        "lifetime": {
            "units": "seconds",
            "value": 7200
        },
        "id": "5291b189-fd84-46e5-84bd-78f40c05d69c",
        "description": ""
    }
}
GET
/v2.0/vpn/ipsecpolicies/{ipsecpolicy_id}

Show IPsec policy

Shows details for an IPsec policy.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 403, 404

Request

Name

In

Type

Description

ipsecpolicy_id

path

string

The ID of the IPsec policy.

Response Parameters

Name

In

Type

Description

ipsecpolicies

body

array

A list of ipsecpolicy objects.

ipsecpolicy

body

object

An ipsecpolicy object.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

auth_algorithm (Optional)

body

string

The authentication hash algorithm. Valid values are sha1, sha256, sha384, sha512, aes-xcbc, aes-cmac. The default is sha1.

encapsulation_mode (Optional)

body

string

The encapsulation mode. A valid value is tunnel or transport. Default is tunnel.

encryption_algorithm (Optional)

body

string

The encryption algorithm. A valid value is 3des, aes-128, aes-192, aes-256. Additional values for AES CCM and GCM modes are defined (e.g. aes-256-ccm-16, aes-256-gcm-16) for all combinations of key length 128, 192, 256 bits and ICV length 8, 12, 16 octets. Default is aes-128.

pfs (Optional)

body

string

Perfect forward secrecy (PFS). A valid value is Group2, Group5, Group14 to Group31. Default is Group5.

value (Optional)

body

integer

The lifetime value, as a positive integer. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

transform_protocol (Optional)

body

string

The transform protocol. A valid value is ESP, AH, or AH- ESP. Default is ESP.

units (Optional)

body

string

The units for the lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

lifetime (Optional)

body

object

The lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

id

body

string

The ID of the IPsec policy.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

Response Example

{
    "ipsecpolicy": {
        "name": "ipsecpolicy1",
        "transform_protocol": "esp",
        "auth_algorithm": "sha1",
        "encapsulation_mode": "tunnel",
        "encryption_algorithm": "aes-128",
        "pfs": "group14",
        "project_id": "ccb81365fe36411a9011e90491fe1330",
        "tenant_id": "ccb81365fe36411a9011e90491fe1330",
        "lifetime": {
            "units": "seconds",
            "value": 3600
        },
        "id": "5291b189-fd84-46e5-84bd-78f40c05d69c",
        "description": ""
    }
}
PUT
/v2.0/vpn/ipsecpolicies/{ipsecpolicy_id}

Update IPsec policy

Updates policy settings in an IPsec policy.

Normal response codes: 200

Error response codes: 400, 401, 404

Request

Name

In

Type

Description

ipsecpolicy_id

path

string

The ID of the IPsec policy.

ipsecpolicy

body

object

An ipsecpolicy object.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

transform_protocol (Optional)

body

string

The transform protocol. A valid value is ESP, AH, or AH- ESP. Default is ESP.

auth_algorithm (Optional)

body

string

The authentication hash algorithm. Valid values are sha1, sha256, sha384, sha512, aes-xcbc, aes-cmac. The default is sha1.

encapsulation_mode (Optional)

body

string

The encapsulation mode. A valid value is tunnel or transport. Default is tunnel.

encryption_algorithm (Optional)

body

string

The encryption algorithm. A valid value is 3des, aes-128, aes-192, aes-256. Additional values for AES CCM and GCM modes are defined (e.g. aes-256-ccm-16, aes-256-gcm-16) for all combinations of key length 128, 192, 256 bits and ICV length 8, 12, 16 octets. Default is aes-128.

pfs (Optional)

body

string

Perfect forward secrecy (PFS). A valid value is Group2, Group5, Group14 to Group31. Default is Group5.

value (Optional)

body

integer

The lifetime value, as a positive integer. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

units (Optional)

body

string

The units for the lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

lifetime (Optional)

body

object

The lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

Request Example

{
    "ipsecpolicy": {
        "pfs": "group14"
    }
}

Response Parameters

Name

In

Type

Description

ipsecpolicies

body

array

A list of ipsecpolicy objects.

ipsecpolicy

body

object

An ipsecpolicy object.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

auth_algorithm (Optional)

body

string

The authentication hash algorithm. Valid values are sha1, sha256, sha384, sha512, aes-xcbc, aes-cmac. The default is sha1.

encapsulation_mode (Optional)

body

string

The encapsulation mode. A valid value is tunnel or transport. Default is tunnel.

encryption_algorithm (Optional)

body

string

The encryption algorithm. A valid value is 3des, aes-128, aes-192, aes-256. Additional values for AES CCM and GCM modes are defined (e.g. aes-256-ccm-16, aes-256-gcm-16) for all combinations of key length 128, 192, 256 bits and ICV length 8, 12, 16 octets. Default is aes-128.

pfs (Optional)

body

string

Perfect forward secrecy (PFS). A valid value is Group2, Group5, Group14 to Group31. Default is Group5.

value (Optional)

body

integer

The lifetime value, as a positive integer. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

transform_protocol (Optional)

body

string

The transform protocol. A valid value is ESP, AH, or AH- ESP. Default is ESP.

units (Optional)

body

string

The units for the lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

lifetime (Optional)

body

object

The lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime. Default unit is seconds and default value is 3600.

id

body

string

The ID of the IPsec policy.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

Response Example

{
    "ipsecpolicy": {
        "name": "ipsecpolicy1",
        "transform_protocol": "esp",
        "auth_algorithm": "sha1",
        "encapsulation_mode": "tunnel",
        "encryption_algorithm": "aes-128",
        "pfs": "group14",
        "project_id": "ccb81365fe36411a9011e90491fe1330",
        "tenant_id": "ccb81365fe36411a9011e90491fe1330",
        "lifetime": {
            "units": "seconds",
            "value": 3600
        },
        "id": "5291b189-fd84-46e5-84bd-78f40c05d69c",
        "description": ""
    }
}
DELETE
/v2.0/vpn/ipsecpolicies/{ipsecpolicy_id}

Remove IPsec policy

Removes an IPsec policy.

Normal response codes: 204

Error response codes: 401, 404, 409

Request

Name

In

Type

Description

ipsecpolicy_id

path

string

The ID of the IPsec policy.

Response

There is no body content for the response of a successful DELETE request.

GET
/v2.0/vpn/ipsec-site-connections

List IPsec connections

Lists all IPsec connections.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401, 403

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

auth_mode (Optional)

body

string

The authentication mode. A valid value is psk, which is the default.

ikepolicy_id

body

string

The ID of the IKE policy.

vpnservice_id

body

string

The ID of the VPN service.

local_ep_group_id (Optional)

body

string

The ID for the endpoint group that contains private subnets for the local side of the connection. Yo must specify this parameter with the peer_ep_group_id parameter unless in backward- compatible mode where peer_cidrs is provided with a subnet_id for the VPN service.

peer_address

body

string

The peer gateway public IPv4 or IPv6 address or FQDN.

id (Optional)

body

string

The ID of the IPsec site-to-site connection.

route_mode (Optional)

body

string

The route mode. A valid value is static, which is the default.

ipsecpolicy_id

body

string

The ID of the IPsec policy.

peer_id

body

string

The peer router identity for authentication. A valid value is an IPv4 address, IPv6 address, e-mail address, key ID, or FQDN. Typically, this value matches the peer_address value.

status

body

string

Indicates whether the IPsec connection is currently operational. Values are ACTIVE, DOWN, BUILD, ERROR, PENDING_CREATE, PENDING_UPDATE, or PENDING_DELETE.

psk

body

string

The pre-shared key. A valid value is any string.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

initiator (Optional)

body

string

Indicates whether this VPN can only respond to connections or both respond to and initiate connections. A valid value is response- only or bi-directional. Default is bi-directional.

peer_cidrs (Optional)

body

array

(Deprecated) Unique list of valid peer private CIDRs in the form < net_address > / < prefix > .

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

interval (Optional)

body

integer

The dead peer detection (DPD) interval, in seconds. A valid value is a positive integer. Default is 30.

mtu

body

integer

The maximum transmission unit (MTU) value to address fragmentation. Minimum value is 68 for IPv4, and 1280 for IPv6.

peer_ep_group_id (Optional)

body

string

The ID for the endpoint group that contains private CIDRs in the form < net_address > / < prefix > for the peer side of the connection. You must specify this parameter with the local_ep_group_id parameter unless in backward-compatible mode where peer_cidrs is provided with a subnet_id for the VPN service.

dpd (Optional)

body

object

A dictionary with dead peer detection (DPD) protocol controls.

timeout

body

integer

The dead peer detection (DPD) timeout in seconds. A valid value is a positive integer that is greater than the DPD interval value. Default is 120.

action

body

string

The dead peer detection (DPD) action. A valid value is clear, hold, restart, disabled, or restart-by-peer. Default value is hold.

local_id (Optional)

body

string

An ID to be used instead of the external IP address for a virtual router used in traffic between instances on different networks in east-west traffic. Most often, local ID would be domain name, email address, etc. If this is not configured then the external IP address will be used as the ID.

Response Example

{
    "ipsec_site_connections": [
        {
            "status": "PENDING CREATE",
            "psk": "secret",
            "initiator": "bi-directional",
            "name": "vpnconnection1",
            "admin_state_up": true,
            "project_id": "10039663455a446d8ba2cbb058b0f578",
            "tenant_id": "10039663455a446d8ba2cbb058b0f578",
            "auth_mode": "psk",
            "peer_cidrs": [],
            "mtu": 1500,
            "peer_ep_group_id": "9ad5a7e0-6dac-41b4-b20d-a7b8645fddf1",
            "ikepolicy_id": "9b00d6b0-6c93-4ca5-9747-b8ade7bb514f",
            "vpnservice_id": "5c561d9d-eaea-45f6-ae3e-08d1a7080828",
            "dpd": {
                "action": "hold",
                "interval": 30,
                "timeout": 120
            },
            "route_mode": "static",
            "ipsecpolicy_id": "e6e23d0c-9519-4d52-8ea4-5b1f96d857b1",
            "local_ep_group_id": "3e1815dd-e212-43d0-8f13-b494fa553e68",
            "peer_address": "172.24.4.226",
            "peer_id": "172.24.4.226",
            "id": "851f280f-5639-4ea3-81aa-e298525ab74b",
            "description": ""
        }
    ]
}
POST
/v2.0/vpn/ipsec-site-connections

Create IPsec connection

Creates a site-to-site IPsec connection for a service.

Normal response codes: 201

Error response codes: 400, 401

Request

Name

In

Type

Description

ipsec_site_connection

body

object

An ipsec_site_connection object.

auth_mode (Optional)

body

string

The authentication mode. A valid value is psk, which is the default.

ikepolicy_id (Optional)

body

string

The ID of the IKE policy.

vpnservice_id (Optional)

body

string

The ID of the VPN service.

local_ep_group_id (Optional)

body

string

The ID for the endpoint group that contains private subnets for the local side of the connection. Yo must specify this parameter with the peer_ep_group_id parameter unless in backward- compatible mode where peer_cidrs is provided with a subnet_id for the VPN service.

peer_address

body

string

The peer gateway public IPv4 or IPv6 address or FQDN.

route_mode (Optional)

body

string

The route mode. A valid value is static, which is the default.

ipsecpolicy_id (Optional)

body

string

The ID of the IPsec policy.

peer_id

body

string

The peer router identity for authentication. A valid value is an IPv4 address, IPv6 address, e-mail address, key ID, or FQDN. Typically, this value matches the peer_address value.

psk

body

string

The pre-shared key. A valid value is any string.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

initiator (Optional)

body

string

Indicates whether this VPN can only respond to connections or both respond to and initiate connections. A valid value is response- only or bi-directional. Default is bi-directional.

peer_cidrs (Optional)

body

array

(Deprecated) Unique list of valid peer private CIDRs in the form < net_address > / < prefix > .

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

interval (Optional)

body

integer

The dead peer detection (DPD) interval, in seconds. A valid value is a positive integer. Default is 30.

mtu

body

integer

The maximum transmission unit (MTU) value to address fragmentation. Minimum value is 68 for IPv4, and 1280 for IPv6.

peer_ep_group_id (Optional)

body

string

The ID for the endpoint group that contains private CIDRs in the form < net_address > / < prefix > for the peer side of the connection. You must specify this parameter with the local_ep_group_id parameter unless in backward-compatible mode where peer_cidrs is provided with a subnet_id for the VPN service.

dpd (Optional)

body

object

A dictionary with dead peer detection (DPD) protocol controls.

timeout

body

integer

The dead peer detection (DPD) timeout in seconds. A valid value is a positive integer that is greater than the DPD interval value. Default is 120.

action

body

string

The dead peer detection (DPD) action. A valid value is clear, hold, restart, disabled, or restart-by-peer. Default value is hold.

local_id (Optional)

body

string

An ID to be used instead of the external IP address for a virtual router used in traffic between instances on different networks in east-west traffic. Most often, local ID would be domain name, email address, etc. If this is not configured then the external IP address will be used as the ID.

Request Example

{
    "ipsec_site_connection": {
        "psk": "secret",
        "initiator": "bi-directional",
        "ipsecpolicy_id": "e6e23d0c-9519-4d52-8ea4-5b1f96d857b1",
        "admin_state_up": true,
        "mtu": "1500",
        "peer_ep_group_id": "9ad5a7e0-6dac-41b4-b20d-a7b8645fddf1",
        "ikepolicy_id": "9b00d6b0-6c93-4ca5-9747-b8ade7bb514f",
        "vpnservice_id": "5c561d9d-eaea-45f6-ae3e-08d1a7080828",
        "local_ep_group_id": "3e1815dd-e212-43d0-8f13-b494fa553e68",
        "peer_address": "172.24.4.233",
        "peer_id": "172.24.4.233",
        "name": "vpnconnection1"
    }
}

Response Parameters

Name

In

Type

Description

ipsec_site_connection

body

object

An ipsec_site_connection object.

auth_mode (Optional)

body

string

The authentication mode. A valid value is psk, which is the default.

ikepolicy_id

body

string

The ID of the IKE policy.

vpnservice_id

body

string

The ID of the VPN service.

local_ep_group_id (Optional)

body

string

The ID for the endpoint group that contains private subnets for the local side of the connection. Yo must specify this parameter with the peer_ep_group_id parameter unless in backward- compatible mode where peer_cidrs is provided with a subnet_id for the VPN service.

peer_address

body

string

The peer gateway public IPv4 or IPv6 address or FQDN.

id (Optional)

body

string

The ID of the IPsec site-to-site connection.

route_mode (Optional)

body

string

The route mode. A valid value is static, which is the default.

ipsecpolicy_id

body

string

The ID of the IPsec policy.

peer_id

body

string

The peer router identity for authentication. A valid value is an IPv4 address, IPv6 address, e-mail address, key ID, or FQDN. Typically, this value matches the peer_address value.

status

body

string

Indicates whether the IPsec connection is currently operational. Values are ACTIVE, DOWN, BUILD, ERROR, PENDING_CREATE, PENDING_UPDATE, or PENDING_DELETE.

psk

body

string

The pre-shared key. A valid value is any string.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

initiator (Optional)

body

string

Indicates whether this VPN can only respond to connections or both respond to and initiate connections. A valid value is response- only or bi-directional. Default is bi-directional.

peer_cidrs (Optional)

body

array

(Deprecated) Unique list of valid peer private CIDRs in the form < net_address > / < prefix > .

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

interval (Optional)

body

integer

The dead peer detection (DPD) interval, in seconds. A valid value is a positive integer. Default is 30.

mtu

body

integer

The maximum transmission unit (MTU) value to address fragmentation. Minimum value is 68 for IPv4, and 1280 for IPv6.

peer_ep_group_id (Optional)

body

string

The ID for the endpoint group that contains private CIDRs in the form < net_address > / < prefix > for the peer side of the connection. You must specify this parameter with the local_ep_group_id parameter unless in backward-compatible mode where peer_cidrs is provided with a subnet_id for the VPN service.

dpd (Optional)

body

object

A dictionary with dead peer detection (DPD) protocol controls.

timeout

body

integer

The dead peer detection (DPD) timeout in seconds. A valid value is a positive integer that is greater than the DPD interval value. Default is 120.

action

body

string

The dead peer detection (DPD) action. A valid value is clear, hold, restart, disabled, or restart-by-peer. Default value is hold.

local_id (Optional)

body

string

An ID to be used instead of the external IP address for a virtual router used in traffic between instances on different networks in east-west traffic. Most often, local ID would be domain name, email address, etc. If this is not configured then the external IP address will be used as the ID.

Response Example

{
    "ipsec_site_connection": {
        "status": "PENDING_CREATE",
        "psk": "secret",
        "initiator": "bi-directional",
        "name": "vpnconnection1",
        "admin_state_up": true,
        "project_id": "10039663455a446d8ba2cbb058b0f578",
        "tenant_id": "10039663455a446d8ba2cbb058b0f578",
        "auth_mode": "psk",
        "peer_cidrs": [],
        "mtu": 1500,
        "peer_ep_group_id": "9ad5a7e0-6dac-41b4-b20d-a7b8645fddf1",
        "ikepolicy_id": "9b00d6b0-6c93-4ca5-9747-b8ade7bb514f",
        "vpnservice_id": "5c561d9d-eaea-45f6-ae3e-08d1a7080828",
        "dpd": {
            "action": "hold",
            "interval": 30,
            "timeout": 120
        },
        "route_mode": "static",
        "ipsecpolicy_id": "e6e23d0c-9519-4d52-8ea4-5b1f96d857b1",
        "local_ep_group_id": "3e1815dd-e212-43d0-8f13-b494fa553e68",
        "peer_address": "172.24.4.233",
        "peer_id": "172.24.4.233",
        "id": "851f280f-5639-4ea3-81aa-e298525ab74b",
        "description": ""
    }
}
GET
/v2.0/vpn/ipsec-site-connections/{connection_id}

Show IPsec connection

Shows details for an IPsec connection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 403, 404

Request

Name

In

Type

Description

connection_id

path

string

The ID of the IPsec site-to-site connection.

Response Parameters

Name

In

Type

Description

auth_mode (Optional)

body

string

The authentication mode. A valid value is psk, which is the default.

ikepolicy_id

body

string

The ID of the IKE policy.

vpnservice_id

body

string

The ID of the VPN service.

local_ep_group_id (Optional)

body

string

The ID for the endpoint group that contains private subnets for the local side of the connection. Yo must specify this parameter with the peer_ep_group_id parameter unless in backward- compatible mode where peer_cidrs is provided with a subnet_id for the VPN service.

peer_address

body

string

The peer gateway public IPv4 or IPv6 address or FQDN.

id (Optional)

body

string

The ID of the IPsec site-to-site connection.

ipsec_site_connection

body

object

An ipsec_site_connection object.

route_mode (Optional)

body

string

The route mode. A valid value is static, which is the default.

ipsecpolicy_id

body

string

The ID of the IPsec policy.

peer_id

body

string

The peer router identity for authentication. A valid value is an IPv4 address, IPv6 address, e-mail address, key ID, or FQDN. Typically, this value matches the peer_address value.

status

body

string

Indicates whether the IPsec connection is currently operational. Values are ACTIVE, DOWN, BUILD, ERROR, PENDING_CREATE, PENDING_UPDATE, or PENDING_DELETE.

psk

body

string

The pre-shared key. A valid value is any string.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

initiator (Optional)

body

string

Indicates whether this VPN can only respond to connections or both respond to and initiate connections. A valid value is response- only or bi-directional. Default is bi-directional.

peer_cidrs (Optional)

body

array

(Deprecated) Unique list of valid peer private CIDRs in the form < net_address > / < prefix > .

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

interval (Optional)

body

integer

The dead peer detection (DPD) interval, in seconds. A valid value is a positive integer. Default is 30.

mtu

body

integer

The maximum transmission unit (MTU) value to address fragmentation. Minimum value is 68 for IPv4, and 1280 for IPv6.

peer_ep_group_id (Optional)

body

string

The ID for the endpoint group that contains private CIDRs in the form < net_address > / < prefix > for the peer side of the connection. You must specify this parameter with the local_ep_group_id parameter unless in backward-compatible mode where peer_cidrs is provided with a subnet_id for the VPN service.

dpd (Optional)

body

object

A dictionary with dead peer detection (DPD) protocol controls.

timeout

body

integer

The dead peer detection (DPD) timeout in seconds. A valid value is a positive integer that is greater than the DPD interval value. Default is 120.

action

body

string

The dead peer detection (DPD) action. A valid value is clear, hold, restart, disabled, or restart-by-peer. Default value is hold.

local_id (Optional)

body

string

An ID to be used instead of the external IP address for a virtual router used in traffic between instances on different networks in east-west traffic. Most often, local ID would be domain name, email address, etc. If this is not configured then the external IP address will be used as the ID.

Response Example

{
    "ipsec_site_connection": {
        "status": "DOWN",
        "psk": "secret",
        "initiator": "bi-directional",
        "name": "vpnconnection1",
        "admin_state_up": true,
        "project_id": "10039663455a446d8ba2cbb058b0f578",
        "tenant_id": "10039663455a446d8ba2cbb058b0f578",
        "auth_mode": "psk",
        "peer_cidrs": [],
        "mtu": 1500,
        "peer_ep_group_id": "9ad5a7e0-6dac-41b4-b20d-a7b8645fddf1",
        "ikepolicy_id": "9b00d6b0-6c93-4ca5-9747-b8ade7bb514f",
        "vpnservice_id": "5c561d9d-eaea-45f6-ae3e-08d1a7080828",
        "dpd": {
            "action": "hold",
            "interval": 30,
            "timeout": 120
        },
        "route_mode": "static",
        "ipsecpolicy_id": "e6e23d0c-9519-4d52-8ea4-5b1f96d857b1",
        "local_ep_group_id": "3e1815dd-e212-43d0-8f13-b494fa553e68",
        "peer_address": "172.24.4.226",
        "peer_id": "172.24.4.226",
        "id": "851f280f-5639-4ea3-81aa-e298525ab74b",
        "description": ""
    }
}
PUT
/v2.0/vpn/ipsec-site-connections/{connection_id}

Update IPsec connection

Updates connection settings for an IPsec connection.

Normal response codes: 200

Error response codes: 400, 401, 404

Request

Name

In

Type

Description

connection_id

path

string

The ID of the IPsec site-to-site connection.

ipsec_site_connection

body

object

An ipsec_site_connection object.

psk

body

string

The pre-shared key. A valid value is any string.

initiator (Optional)

body

string

Indicates whether this VPN can only respond to connections or both respond to and initiate connections. A valid value is response- only or bi-directional. Default is bi-directional.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

interval (Optional)

body

integer

The dead peer detection (DPD) interval, in seconds. A valid value is a positive integer. Default is 30.

peer_cidrs (Optional)

body

array

(Deprecated) Unique list of valid peer private CIDRs in the form < net_address > / < prefix > .

mtu

body

integer

The maximum transmission unit (MTU) value to address fragmentation. Minimum value is 68 for IPv4, and 1280 for IPv6.

peer_ep_group_id (Optional)

body

string

The ID for the endpoint group that contains private CIDRs in the form < net_address > / < prefix > for the peer side of the connection. You must specify this parameter with the local_ep_group_id parameter unless in backward-compatible mode where peer_cidrs is provided with a subnet_id for the VPN service.

local_ep_group_id (Optional)

body

string

The ID for the endpoint group that contains private subnets for the local side of the connection. Yo must specify this parameter with the peer_ep_group_id parameter unless in backward- compatible mode where peer_cidrs is provided with a subnet_id for the VPN service.

dpd (Optional)

body

object

A dictionary with dead peer detection (DPD) protocol controls.

timeout

body

integer

The dead peer detection (DPD) timeout in seconds. A valid value is a positive integer that is greater than the DPD interval value. Default is 120.

action

body

string

The dead peer detection (DPD) action. A valid value is clear, hold, restart, disabled, or restart-by-peer. Default value is hold.

peer_address

body

string

The peer gateway public IPv4 or IPv6 address or FQDN.

peer_id

body

string

The peer router identity for authentication. A valid value is an IPv4 address, IPv6 address, e-mail address, key ID, or FQDN. Typically, this value matches the peer_address value.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

local_id (Optional)

body

string

An ID to be used instead of the external IP address for a virtual router used in traffic between instances on different networks in east-west traffic. Most often, local ID would be domain name, email address, etc. If this is not configured then the external IP address will be used as the ID.

Request Example

{
    "ipsec_site_connection": {
        "mtu": "2000"
    }
}

Response Parameters

Name

In

Type

Description

auth_mode (Optional)

body

string

The authentication mode. A valid value is psk, which is the default.

ikepolicy_id

body

string

The ID of the IKE policy.

vpnservice_id

body

string

The ID of the VPN service.

local_ep_group_id (Optional)

body

string

The ID for the endpoint group that contains private subnets for the local side of the connection. Yo must specify this parameter with the peer_ep_group_id parameter unless in backward- compatible mode where peer_cidrs is provided with a subnet_id for the VPN service.

peer_address

body

string

The peer gateway public IPv4 or IPv6 address or FQDN.

id (Optional)

body

string

The ID of the IPsec site-to-site connection.

ipsec_site_connection

body

object

An ipsec_site_connection object.

route_mode (Optional)

body

string

The route mode. A valid value is static, which is the default.

ipsecpolicy_id

body

string

The ID of the IPsec policy.

peer_id

body

string

The peer router identity for authentication. A valid value is an IPv4 address, IPv6 address, e-mail address, key ID, or FQDN. Typically, this value matches the peer_address value.

status

body

string

Indicates whether the IPsec connection is currently operational. Values are ACTIVE, DOWN, BUILD, ERROR, PENDING_CREATE, PENDING_UPDATE, or PENDING_DELETE.

psk

body

string

The pre-shared key. A valid value is any string.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

initiator (Optional)

body

string

Indicates whether this VPN can only respond to connections or both respond to and initiate connections. A valid value is response- only or bi-directional. Default is bi-directional.

peer_cidrs (Optional)

body

array

(Deprecated) Unique list of valid peer private CIDRs in the form < net_address > / < prefix > .

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

interval (Optional)

body

integer

The dead peer detection (DPD) interval, in seconds. A valid value is a positive integer. Default is 30.

mtu

body

integer

The maximum transmission unit (MTU) value to address fragmentation. Minimum value is 68 for IPv4, and 1280 for IPv6.

peer_ep_group_id (Optional)

body

string

The ID for the endpoint group that contains private CIDRs in the form < net_address > / < prefix > for the peer side of the connection. You must specify this parameter with the local_ep_group_id parameter unless in backward-compatible mode where peer_cidrs is provided with a subnet_id for the VPN service.

dpd (Optional)

body

object

A dictionary with dead peer detection (DPD) protocol controls.

timeout

body

integer

The dead peer detection (DPD) timeout in seconds. A valid value is a positive integer that is greater than the DPD interval value. Default is 120.

action

body

string

The dead peer detection (DPD) action. A valid value is clear, hold, restart, disabled, or restart-by-peer. Default value is hold.

local_id (Optional)

body

string

An ID to be used instead of the external IP address for a virtual router used in traffic between instances on different networks in east-west traffic. Most often, local ID would be domain name, email address, etc. If this is not configured then the external IP address will be used as the ID.

Response Example

{
    "ipsec_site_connection": {
        "status": "DOWN",
        "psk": "secret",
        "initiator": "bi-directional",
        "name": "vpnconnection1",
        "admin_state_up": true,
        "project_id": "10039663455a446d8ba2cbb058b0f578",
        "tenant_id": "10039663455a446d8ba2cbb058b0f578",
        "auth_mode": "psk",
        "peer_cidrs": [],
        "mtu": 2000,
        "peer_ep_group_id": "9ad5a7e0-6dac-41b4-b20d-a7b8645fddf1",
        "ikepolicy_id": "9b00d6b0-6c93-4ca5-9747-b8ade7bb514f",
        "vpnservice_id": "5c561d9d-eaea-45f6-ae3e-08d1a7080828",
        "dpd": {
            "action": "hold",
            "interval": 30,
            "timeout": 120
        },
        "route_mode": "static",
        "ipsecpolicy_id": "e6e23d0c-9519-4d52-8ea4-5b1f96d857b1",
        "local_ep_group_id": "3e1815dd-e212-43d0-8f13-b494fa553e68",
        "peer_address": "172.24.4.233",
        "peer_id": "172.24.4.233",
        "id": "851f280f-5639-4ea3-81aa-e298525ab74b",
        "description": "New description"
    }
}
DELETE
/v2.0/vpn/ipsec-site-connections/{connection_id}

Remove IPsec connection

Removes an IPsec connection.

Normal response codes: 204

Error response codes: 401, 404, 409

Request

Name

In

Type

Description

connection_id

path

string

The ID of the IPsec site-to-site connection.

Response

There is no body content for the response of a successful DELETE request.

GET
/v2.0/vpn/endpoint-groups

List VPN endpoint groups

Lists VPN endpoint groups.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401, 403

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

endpoints

body

array

List of endpoints of the same type, for the endpoint group. The values will depend on type.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

type

body

string

The type of the endpoints in the group. A valid value is subnet, cidr, network, router, or vlan. Only subnet and cidr are supported at this moment.

id

body

string

The ID of the VPN endpoint group.

Response Example

{
    "endpoint_groups": [
        {
            "description": "",
            "project_id": "4ad57e7ce0b24fca8f12b9834d91079d",
            "tenant_id": "4ad57e7ce0b24fca8f12b9834d91079d",
            "endpoints": [
                "a3da778c-adfb-46db-88b3-d2ce53290a89"
            ],
            "type": "subnet",
            "id": "6bf34c7c-864c-4948-a6d4-db791669f9d4",
            "name": "locals"
        },
        {
            "description": "",
            "project_id": "4ad57e7ce0b24fca8f12b9834d91079d",
            "tenant_id": "4ad57e7ce0b24fca8f12b9834d91079d",
            "endpoints": [
                "10.2.0.0/24",
                "10.3.0.0/24"
            ],
            "type": "cidr",
            "id": "6ecd9cf3-ca64-46c7-863f-f2eb1b9e838a",
            "name": "peers"
        }
    ]
}
POST
/v2.0/vpn/endpoint-groups

Create VPN endpoint group

Creates a VPN endpoint group.

The endpoint group contains one or more endpoints of a specific type that you can use to create a VPN connections.

Normal response codes: 201

Error response codes: 400, 401

Request

Name

In

Type

Description

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

endpoints

body

array

List of endpoints of the same type, for the endpoint group. The values will depend on type.

type

body

string

The type of the endpoints in the group. A valid value is subnet, cidr, network, router, or vlan. Only subnet and cidr are supported at this moment.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

Request Example

{
    "endpoint_group": {
        "endpoints": [
            "10.2.0.0/24",
            "10.3.0.0/24"
        ],
        "type": "cidr",
        "name": "peers"
    }
}

Response Parameters

Name

In

Type

Description

endpoints

body

array

List of endpoints of the same type, for the endpoint group. The values will depend on type.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

type

body

string

The type of the endpoints in the group. A valid value is subnet, cidr, network, router, or vlan. Only subnet and cidr are supported at this moment.

id

body

string

The ID of the VPN endpoint group.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

Response Example

{
    "endpoint_group": {
        "description": "",
        "project_id": "4ad57e7ce0b24fca8f12b9834d91079d",
        "tenant_id": "4ad57e7ce0b24fca8f12b9834d91079d",
        "endpoints": [
            "10.2.0.0/24",
            "10.3.0.0/24"
        ],
        "type": "cidr",
        "id": "6ecd9cf3-ca64-46c7-863f-f2eb1b9e838a",
        "name": "peers"
    }
}
GET
/v2.0/vpn/endpoint-groups/{endpoint_group_id}

Show VPN endpoint group

Shows details for a VPN endpoint group.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 403, 404

Request

Name

In

Type

Description

endpoint_group_id

path

string

The ID of the VPN endpoint group.

Response Parameters

Name

In

Type

Description

endpoints

body

array

List of endpoints of the same type, for the endpoint group. The values will depend on type.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

type

body

string

The type of the endpoints in the group. A valid value is subnet, cidr, network, router, or vlan. Only subnet and cidr are supported at this moment.

id

body

string

The ID of the VPN endpoint group.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

Response Example

{
    "endpoint_group": {
        "description": "",
        "project_id": "4ad57e7ce0b24fca8f12b9834d91079d",
        "tenant_id": "4ad57e7ce0b24fca8f12b9834d91079d",
        "endpoints": [
            "10.2.0.0/24",
            "10.3.0.0/24"
        ],
        "type": "cidr",
        "id": "6ecd9cf3-ca64-46c7-863f-f2eb1b9e838a",
        "name": "peers"
    }
}
PUT
/v2.0/vpn/endpoint-groups/{endpoint_group_id}

Update VPN endpoint group

Updates settings for a VPN endpoint group.

Normal response codes: 200

Error response codes: 400, 401, 404

Request

Name

In

Type

Description

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

endpoint_group_id

path

string

The ID of the VPN endpoint group.

Request Example

{
    "endpoint_group": {
        "description": "New description"
    }
}

Response Parameters

Name

In

Type

Description

endpoints

body

array

List of endpoints of the same type, for the endpoint group. The values will depend on type.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

type

body

string

The type of the endpoints in the group. A valid value is subnet, cidr, network, router, or vlan. Only subnet and cidr are supported at this moment.

id

body

string

The ID of the VPN endpoint group.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

Response Example

{
    "endpoint_group": {
        "description": "New description",
        "project_id": "4ad57e7ce0b24fca8f12b9834d91079d",
        "tenant_id": "4ad57e7ce0b24fca8f12b9834d91079d",
        "endpoints": [
            "10.2.0.0/24",
            "10.3.0.0/24"
        ],
        "type": "cidr",
        "id": "6ecd9cf3-ca64-46c7-863f-f2eb1b9e838a",
        "name": "peers"
    }
}
DELETE
/v2.0/vpn/endpoint-groups/{endpoint_group_id}

Remove VPN endpoint group

Removes a VPN endpoint group.

Normal response codes: 204

Error response codes: 401, 404, 409

Request

Name

In

Type

Description

endpoint_group_id

path

string

The ID of the VPN endpoint group.

Response

There is no body content for the response of a successful DELETE request.

GET
/v2.0/vpn/vpnservices

List VPN services

Lists all VPN services.

The list might be empty.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401, 403

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

vpnservices

body

array

A list of VPN service objects.

router_id

path

string

The ID of the router.

status

body

string

Indicates whether IPsec VPN service is currently operational. Values are ACTIVE, DOWN, BUILD, ERROR, PENDING_CREATE, PENDING_UPDATE, or PENDING_DELETE.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

external_v6_ip

body

string

Read-only external (public) IPv6 address that is used for the VPN service. The VPN plugin sets this address if an IPv6 interface is available.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

subnet_id (Optional)

body

string

If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

external_v4_ip

body

string

Read-only external (public) IPv4 address that is used for the VPN service. The VPN plugin sets this address if an IPv4 interface is available.

id

body

string

The ID of the VPN service.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

flavor_id

body

string

The ID of the flavor.

Response Example

{
    "vpnservices": [
        {
            "router_id": "66e3b16c-8ce5-40fb-bb49-ab6d8dc3f2aa",
            "status": "PENDING_CREATE",
            "name": "myservice",
            "external_v6_ip": "2001:db8::1",
            "admin_state_up": true,
            "subnet_id": null,
            "project_id": "10039663455a446d8ba2cbb058b0f578",
            "tenant_id": "10039663455a446d8ba2cbb058b0f578",
            "external_v4_ip": "172.32.1.11",
            "id": "5c561d9d-eaea-45f6-ae3e-08d1a7080828",
            "description": "",
            "flavor_id": null
        }
    ]
}
POST
/v2.0/vpn/vpnservices

Create VPN service

Creates a VPN service.

The service is associated with a router. After you create the service, it can contain multiple VPN connections.

An optional flavor_id attribute can be passed to enable dynamic selection of an appropriate provider if configured by the operator. It is only available when vpn-flavors extension is enabled. The basic selection algorithm chooses the provider in the first service profile currently associated with flavor. This option can only be set in POST operation.

Normal response codes: 201

Error response codes: 400, 401

Request

Name

In

Type

Description

vpnservice

body

object

A vpnservice object.

router_id

path

string

The ID of the router.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

subnet_id (Optional)

body

string

If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

flavor_id (Optional)

body

string

The ID of the flavor.

Request Example

{
    "vpnservice": {
        "subnet_id": null,
        "router_id": "66e3b16c-8ce5-40fb-bb49-ab6d8dc3f2aa",
        "name": "myservice",
        "admin_state_up": true,
        "flavor_id": null
    }
}

Response Parameters

Name

In

Type

Description

vpnservice

body

object

A vpnservice object.

router_id

path

string

The ID of the router.

status

body

string

Indicates whether IPsec VPN service is currently operational. Values are ACTIVE, DOWN, BUILD, ERROR, PENDING_CREATE, PENDING_UPDATE, or PENDING_DELETE.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

external_v6_ip

body

string

Read-only external (public) IPv6 address that is used for the VPN service. The VPN plugin sets this address if an IPv6 interface is available.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

subnet_id (Optional)

body

string

If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

external_v4_ip

body

string

Read-only external (public) IPv4 address that is used for the VPN service. The VPN plugin sets this address if an IPv4 interface is available.

id

body

string

The ID of the VPN service.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

flavor_id

body

string

The ID of the flavor.

Response Example

{
    "vpnservice": {
        "router_id": "66e3b16c-8ce5-40fb-bb49-ab6d8dc3f2aa",
        "status": "PENDING_CREATE",
        "name": "myservice",
        "external_v6_ip": "2001:db8::1",
        "admin_state_up": true,
        "subnet_id": null,
        "project_id": "10039663455a446d8ba2cbb058b0f578",
        "tenant_id": "10039663455a446d8ba2cbb058b0f578",
        "external_v4_ip": "172.32.1.11",
        "id": "5c561d9d-eaea-45f6-ae3e-08d1a7080828",
        "description": "",
        "flavor_id": null
    }
}
GET
/v2.0/vpn/vpnservices/{service_id}

Show VPN service details

Shows details for a VPN service.

If the user is not an administrative user and the VPN service object does not belong to the tenant account for the user, the operation returns the Forbidden (403) response code.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 403, 404

Request

Name

In

Type

Description

service_id

path

string

The ID of the VPN service.

Response Parameters

Name

In

Type

Description

vpnservice

body

object

A vpnservice object.

router_id

path

string

The ID of the router.

status

body

string

Indicates whether IPsec VPN service is currently operational. Values are ACTIVE, DOWN, BUILD, ERROR, PENDING_CREATE, PENDING_UPDATE, or PENDING_DELETE.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

external_v6_ip

body

string

Read-only external (public) IPv6 address that is used for the VPN service. The VPN plugin sets this address if an IPv6 interface is available.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

subnet_id (Optional)

body

string

If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

external_v4_ip

body

string

Read-only external (public) IPv4 address that is used for the VPN service. The VPN plugin sets this address if an IPv4 interface is available.

id

body

string

The ID of the VPN service.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

flavor_id

body

string

The ID of the flavor.

Response Example

{
    "vpnservice": {
        "router_id": "66e3b16c-8ce5-40fb-bb49-ab6d8dc3f2aa",
        "status": "PENDING_CREATE",
        "name": "myservice",
        "external_v6_ip": "2001:db8::1",
        "admin_state_up": true,
        "subnet_id": null,
        "project_id": "10039663455a446d8ba2cbb058b0f578",
        "tenant_id": "10039663455a446d8ba2cbb058b0f578",
        "external_v4_ip": "172.32.1.11",
        "id": "5c561d9d-eaea-45f6-ae3e-08d1a7080828",
        "description": "",
        "flavor_id": null
    }
}
PUT
/v2.0/vpn/vpnservices/{service_id}

Update VPN service

Updates a VPN service.

Updates the attributes of a VPN service. You cannot update a service with a PENDING_* status.

Normal response codes: 200

Error response codes: 400, 401, 404

Request

Name

In

Type

Description

vpnservice

body

object

A vpnservice object.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

service_id

path

string

The ID of the VPN service.

Request Example

{
    "vpnservice": {
        "description": "Updated description"
    }
}

Response Parameters

Name

In

Type

Description

vpnservice

body

object

A vpnservice object.

router_id

path

string

The ID of the router.

status

body

string

Indicates whether IPsec VPN service is currently operational. Values are ACTIVE, DOWN, BUILD, ERROR, PENDING_CREATE, PENDING_UPDATE, or PENDING_DELETE.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

external_v6_ip

body

string

Read-only external (public) IPv6 address that is used for the VPN service. The VPN plugin sets this address if an IPv6 interface is available.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

subnet_id (Optional)

body

string

If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

external_v4_ip

body

string

Read-only external (public) IPv4 address that is used for the VPN service. The VPN plugin sets this address if an IPv4 interface is available.

id

body

string

The ID of the VPN service.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

flavor_id

body

string

The ID of the flavor.

Response Example

{
    "vpnservice": {
        "router_id": "881b7b30-4efb-407e-a162-5630a7af3595",
        "status": "ACTIVE",
        "name": "myvpn",
        "admin_state_up": true,
        "subnet_id": null,
        "project_id": "26de9cd6cae94c8cb9f79d660d628e1f",
        "tenant_id": "26de9cd6cae94c8cb9f79d660d628e1f",
        "id": "41bfef97-af4e-4f6b-a5d3-4678859d2485",
        "description": "Updated description",
        "flavor_id": null
    }
}
DELETE
/v2.0/vpn/vpnservices/{service_id}

Remove VPN service

Removes a VPN service.

If the service has connections, the request is rejected.

Normal response codes: 204

Error response codes: 401, 404, 409

Request

Name

In

Type

Description

service_id

path

string

The ID of the VPN service.

Response

There is no body content for the response of a successful DELETE request.

Resource Management

Networking Flavors Framework v2.0 (CURRENT) (flavor, service_profile)

Extension that allows user selection of operator-curated flavors during resource creation.

Users can check if flavor available by performing a GET on the /v2.0/extensions/flavors. If it is unavailable,there is an 404 error response (itemNotFound). Refer Show extension details for more details.

GET
/v2.0/flavors

List flavors

Lists all flavors visible to the project.

The list can be empty.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

id (Optional)

query

string

Filter the list result by the ID of the resource.

service_type (Optional)

query

string

Filter the flavor list result by the type of the flavor.

name (Optional)

query

string

Filter the list result by the human-readable name of the resource.

description (Optional)

query

string

Filter the list result by the human-readable description of the resource.

enabled (Optional)

query

boolean

Filter the flavor list result based on whether the flavor is enabled or not.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a flavor attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • description

  • enabled

  • id

  • name

  • service_type

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

flavors

body

array

A list of flavor objects.

id

body

string

The ID of the flavor.

service_type

body

string

Service type for the flavor. Example: FIREWALL.

name

body

string

Name of the flavor.

description

body

string

The human-readable description for the flavor.

enabled

body

boolean

Indicates whether the flavor is enabled or not. Default is true.

service_profiles

body

array

Service profile UUIDs associated with this flavor.

Response Example

{
    "flavors": [
        {
            "description": "",
            "enabled": true,
            "service_profiles": [],
            "service_type": "FIREWALL",
            "id": "f7b14d9a-b0dc-4fbe-bb14-a0f4970a69e0",
            "name": "dummy"
        }
    ]
}
POST
/v2.0/flavors

Create flavor

Creates a flavor.

This operation establishes a new flavor.

The service_type to which the flavor applies is a required parameter. The corresponding service plugin must have been activated as part of the configuration. Check Service providers for how to see currently loaded service types. Additionally the service plugin needs to support the use of flavors.

Creation currently limited to administrators. Other users will receive a Forbidden 403 response code with a response body NeutronError message expressing that creation is disallowed by policy.

Until one or more service profiles are associated with the flavor by the operator, attempts to use the flavor during resource creations will currently return a Not Found 404 with a response body that indicates no service profile could be found.

If the API cannot fulfill the request due to insufficient data or data that is not valid, the service returns the HTTP Bad Request (400) response code with information about the failure in the response body. Validation errors require that you correct the error and submit the request again.

Normal response codes: 201

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

flavor

body

object

A flavor object.

service_type

body

string

Service type for the flavor. Example: FIREWALL.

enabled (Optional)

body

boolean

Indicates whether the flavor is enabled or not. Default is true.

description (Optional)

body

string

The human-readable description for the flavor.

name (Optional)

body

string

Name of the flavor.

Request Example

{
    "flavor": {
        "service_type": "FIREWALL",
        "enabled": true,
        "name": "dummy",
        "description": "Dummy flavor"
    }
}

Response Parameters

Name

In

Type

Description

flavor

body

object

A flavor object.

id

body

string

The ID of the flavor.

service_type

body

string

Service type for the flavor. Example: FIREWALL.

name

body

string

Name of the flavor.

description

body

string

The human-readable description for the flavor.

enabled

body

boolean

Indicates whether the flavor is enabled or not. Default is true.

service_profiles

body

array

Service profile UUIDs associated with this flavor.

Response Example

{
    "flavor": {
        "id": "7fc0581b-4509-49e1-90eb-c953c877fa4c",
        "name": "dummy",
        "service_type": "FIREWALL",
        "description": "Dummy flavor",
        "enabled": true,
        "service_profiles": []
    }
}
GET
/v2.0/flavors/{flavor_id}

Show flavor details

Shows details for a flavor.

This operation returns a flavor object by ID. If you are not an administrative user and the flavor object is not visible to your project account, the service returns the HTTP Forbidden (403) response code.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 403, 404

Request

Name

In

Type

Description

flavor_id

path

string

The UUID of the flavor.

Response Parameters

Name

In

Type

Description

flavor

body

object

A flavor object.

id

body

string

The ID of the flavor.

service_type

body

string

Service type for the flavor. Example: FIREWALL.

name

body

string

Name of the flavor.

description

body

string

The human-readable description for the flavor.

enabled

body

boolean

Indicates whether the flavor is enabled or not. Default is true.

service_profiles

body

array

Service profile UUIDs associated with this flavor.

Response Example

{
    "flavor": {
        "description": "",
        "enabled": true,
        "service_profiles": [],
        "service_type": "FIREWALL",
        "id": "f7b14d9a-b0dc-4fbe-bb14-a0f4970a69e0",
        "name": "dummy"
    }
}
PUT
/v2.0/flavors/{flavor_id}

Update flavor

Updates a flavor.

The service_type cannot be updated as there may be associated service profiles and consumers depending on the value.

Normal response codes: 200

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

flavor_id

path

string

The UUID of the flavor.

flavor

body

object

A flavor object.

name (Optional)

body

string

Name of the flavor.

description (Optional)

body

string

The human-readable description for the flavor.

enabled (Optional)

body

boolean

Indicates whether the flavor is enabled or not. Default is true.

Request Example

{
    "flavor": {
        "enabled": false,
        "name": "newname",
        "description": "New description"
    }
}

Response Parameters

Name

In

Type

Description

flavor

body

object

A flavor object.

id

body

string

The ID of the flavor.

service_type

body

string

Service type for the flavor. Example: FIREWALL.

name

body

string

Name of the flavor.

description

body

string

The human-readable description for the flavor.

enabled

body

boolean

Indicates whether the flavor is enabled or not. Default is true.

service_profiles

body

array

Service profile UUIDs associated with this flavor.

Response Example

{
    "flavor": {
        "description": "New description",
        "enabled": false,
        "service_profiles": [],
        "service_type": "FIREWALL",
        "id": "7fc0581b-4509-49e1-90eb-c953c877fa4c",
        "name": "newname"
    }
}
DELETE
/v2.0/flavors/{flavor_id}

Delete flavor

Deletes a flavor.

Normal response codes: 204

Error response codes: 401, 403, 404

Request

Name

In

Type

Description

flavor_id

path

string

The UUID of the flavor.

Response

No body content is returned on a successful DELETE.

POST
/v2.0/flavors/{flavor_id}/service_profiles

Associate flavor with a service profile

Associate a flavor with a service profile.

A flavor can be associated with more than one profile.

Will return 409 Conflict if association already exists.

Normal response codes: 201

Error response codes: 400, 401, 403, 404, 409

Request

Name

In

Type

Description

flavor_id

path

string

The UUID of the flavor.

service_profile

body

object

A service_profile object.

id

body

string

The UUID of the service profile.

Request Example

{
    "service_profile": {
        "id": "4e5b9191-ffbe-4f7a-b112-2db98232fd32"
    }
}

Response Parameters

Name

In

Type

Description

service_profile

body

object

A service_profile object.

id

body

string

The ID of the resource.

Response Example

{
    "service_profile": {
        "id": "4e5b9191-ffbe-4f7a-b112-2db98232fd32"
    }
}
DELETE
/v2.0/flavors/{flavor_id}/service_profiles/{profile_id}

Disassociate a flavor.

Disassociate a flavor from a service profile.

Normal response codes: 204

Error response codes: 401, 403, 404

Request

Name

In

Type

Description

profile_id

path

string

The UUID of the service profile.

flavor_id

path

string

The UUID of the flavor.

Response

No body content is returned on a successful disassociation.

GET
/v2.0/service_profiles

List service profiles

Lists all service profiles visible for the tenant account.

The list can be empty.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

id (Optional)

query

string

Filter the list result by the ID of the resource.

enabled (Optional)

query

boolean

Filter the service profile list result based on whether this service profile is enabled or not.

driver (Optional)

query

string

Filter the service profile list result by the driver that this profile uses.

description (Optional)

query

string

Filter the list result by the human-readable description of the resource.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a service profile attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • description

  • driver

  • enabled

  • id

  • metainfo

Response Parameters

Name

In

Type

Description

service_profiles

body

array

Service profile UUIDs associated with this flavor.

id

body

string

The UUID of the service profile.

enabled

body

boolean

Indicates whether this service profile is enabled or not. Default is true.

driver

body

string

Provider driver to use for this profile.

description

body

string

The human-readable description for the service profile.

metainfo

body

string

JSON-formatted meta information of the service profile.

Response Example

{
    "service_profiles": [
        {
            "id": "4e5b9191-ffbe-4f7a-b112-2db98232fd32",
            "enabled": true,
            "driver": "neutron.services.vpn.device_drivers.ipsec.OpenSwanDriver",
            "description": "",
            "metainfo": "{}"
        },
        {
            "id": "684322c5-703a-48a2-8138-34b99942a7ef",
            "enabled": true,
            "driver": "neutron.services.vpn.device_drivers.ipsec.OpenSwanDriver",
            "description": "",
            "metainfo": "{}"
        }
    ]
}
POST
/v2.0/service_profiles

Create service profile

Creates a service profile.

This operation establishes a new service profile that can be associated with one or more flavors.

Either metadata or a driver is required.

If a driver is specified but does not exist, call will return a Not found 404 error with the response body explaining that the driver could not be found.

Creation currently limited to administrators. Other users will receive a Forbidden 403 response code with a response body NeutronError message expressing that creation is disallowed by policy.

If the API cannot fulfill the request due to insufficient data or data that is not valid, the service returns the HTTP Bad Request (400) response code with information about the failure in the response body. Validation errors require that you correct the error and submit the request again.

Normal response codes: 201

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

service_profile

body

object

A service_profile object.

description (Optional)

body

string

The human-readable description for the service profile.

metainfo (Optional)

body

string

JSON-formatted meta information of the service profile.

enabled (Optional)

body

boolean

Indicates whether this service profile is enabled or not. Default is true.

driver (Optional)

body

string

Provider driver to use for this profile.

Request Example

{
    "service_profile": {
        "enabled": "true",
        "driver": "neutron.services.vpn.device_drivers.ipsec.OpenSwanDriver",
        "description": "Dummy profile",
        "metainfo": "{'foo': 'bar'}"
    }
}

Response Parameters

Name

In

Type

Description

service_profile

body

object

A service_profile object.

id

body

string

The UUID of the service profile.

enabled

body

boolean

Indicates whether this service profile is enabled or not. Default is true.

driver

body

string

Provider driver to use for this profile.

description

body

string

The human-readable description for the service profile.

metainfo

body

string

JSON-formatted meta information of the service profile.

Response Example

{
    "service_profile": {
        "enabled": true,
        "metainfo": "{'foo': 'bar'}",
        "driver": "neutron.services.vpn.device_drivers.ipsec.OpenSwanDriver",
        "id": "7c793e5f-9b64-44e0-8b1f-902e59c85a01",
        "description": "Dummy profile"
    }
}
GET
/v2.0/service_profiles/{profile_id}

Show service profile details

Shows details for a service profile.

This operation returns a service profile object by ID. If you are not an administrative user and the object is not visible to your tenant account, the service returns the HTTP Forbidden (403) response code.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 403, 404

Request

Name

In

Type

Description

profile_id

path

string

The UUID of the service profile.

Response Parameters

Name

In

Type

Description

service_profile

body

object

A service_profile object.

id

body

string

The UUID of the service profile.

enabled

body

boolean

Indicates whether this service profile is enabled or not. Default is true.

driver

body

string

Provider driver to use for this profile.

description

body

string

The human-readable description for the service profile.

metainfo

body

string

JSON-formatted meta information of the service profile.

Response Example

{
    "service_profile": {
        "enabled": true,
        "metainfo": "{'foo': 'bar'}",
        "driver": "neutron.services.vpn.device_drivers.ipsec.OpenSwanDriver",
        "id": "7c793e5f-9b64-44e0-8b1f-902e59c85a01",
        "description": "Dummy profile"
    }
}
PUT
/v2.0/service_profiles/{profile_id}

Update service profile

Updates a service profile.

Normal response codes: 200

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

profile_id

path

string

The UUID of the service profile.

service_profile

body

object

A service_profile object.

enabled (Optional)

body

boolean

Indicates whether this service profile is enabled or not. Default is true.

driver (Optional)

body

string

Provider driver to use for this profile.

description (Optional)

body

string

The human-readable description for the service profile.

metainfo (Optional)

body

string

JSON-formatted meta information of the service profile.

Request Example

{
    "service_profile": {
        "enabled": false,
        "driver": "neutron.services.vpn.device_drivers.ipsec.OpenSwanDriver",
        "description": "New description",
        "metainfo": "{'new': 'info'}"
    }
}

Response Parameters

Name

In

Type

Description

service_profile

body

object

A service_profile object.

id

body

string

The UUID of the service profile.

enabled

body

boolean

Indicates whether this service profile is enabled or not. Default is true.

driver

body

string

Provider driver to use for this profile.

description

body

string

The human-readable description for the service profile.

metainfo

body

string

JSON-formatted meta information of the service profile.

Response Example

{
    "service_profile": {
        "enabled": false,
        "metainfo": "{'new': 'info'}",
        "driver": "neutron.services.vpn.device_drivers.ipsec.OpenSwanDriver",
        "id": "7c793e5f-9b64-44e0-8b1f-902e59c85a01",
        "description": "New description"
    }
}
DELETE
/v2.0/service_profiles/{profile_id}

Delete service profile

Deletes a service profile.

Attempting to delete a service profile that is currently associated with a flavor will return a Conflict 409 with a response body containing an in use message.

Either metadata or a driver is required.

Normal response codes: 204

Error response codes: 401, 403, 404, 409

Request

Name

In

Type

Description

profile_id

path

string

The UUID of the service profile.

Response

No body content is returned on a successful DELETE.

Metering labels and rules (metering-labels, metering-label-rules)

Creates, modifies, and deletes OpenStack Layer3 metering labels and rules.

GET
/v2.0/metering/metering-labels

List metering labels

Lists all L3 metering labels that belong to the project.

The list shows the ID for each metering label.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

description (Optional)

query

string

Filter the list result by the human-readable description of the resource.

tenant_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

project_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

shared (Optional)

query

boolean

Admin-only. Filter the list result based on whether the resource is shared across all projects.

id (Optional)

query

string

Filter the list result by the ID of the resource.

name (Optional)

query

string

Filter the list result by the human-readable name of the resource.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a metering label attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • id

  • shared

  • name

  • description

  • tenant_id

  • project_id

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

metering_labels

body

array

A list of metering_label objects.

description

body

string

A human-readable description for the resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

shared

body

boolean

Indicates whether this metering label is shared across all projects.

id

body

string

The ID of the metering label.

name

body

string

Human-readable name of the resource.

Response Example

{
    "metering_labels": [
        {
            "project_id": "45345b0ee1ea477fac0f541b2cb79cd4",
            "tenant_id": "45345b0ee1ea477fac0f541b2cb79cd4",
            "description": "label1 description",
            "name": "label1",
            "id": "a6700594-5b7a-4105-8bfe-723b346ce866",
            "shared": false
        },
        {
            "project_id": "45345b0ee1ea477fac0f541b2cb79cd4",
            "tenant_id": "45345b0ee1ea477fac0f541b2cb79cd4",
            "description": "label2 description",
            "name": "label2",
            "id": "e131d186-b02d-4c0b-83d5-0c0725c4f812",
            "shared": false
        }
    ]
}
POST
/v2.0/metering/metering-labels

Create metering label

Creates an L3 metering label.

Normal response codes: 201

Error response codes: 400, 401, 403

Request

Name

In

Type

Description

metering_label

body

object

A metering_label object.

shared (Optional)

body

boolean

Indicates whether this metering label is shared across all projects.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

tenant_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

project_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

Request Example

{
    "metering_label": {
        "name": "label1",
        "description": "description of label1"
    }
}

Response Parameters

Name

In

Type

Description

metering_label

body

object

A metering_label object.

description

body

string

A human-readable description for the resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

shared

body

boolean

Indicates whether this metering label is shared across all projects.

id

body

string

The ID of the metering label.

name

body

string

Human-readable name of the resource.

Response Example

{
    "metering_label": {
        "project_id": "45345b0ee1ea477fac0f541b2cb79cd4",
        "tenant_id": "45345b0ee1ea477fac0f541b2cb79cd4",
        "description": "description of label1",
        "name": "label1",
        "id": "bc91b832-8465-40a7-a5d8-ba87de442266",
        "shared": false
    }
}
GET
/v2.0/metering/metering-labels/{metering_label_id}

Show metering label details

Shows details for a metering label.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

metering_label_id

path

string

The ID of the metering label.

Request Example

GET /v2.0/metering/metering-labels/a6700594-5b7a-4105-8bfe-723b346ce866 HTTP/1.1
Host: controlnode:9696
User-Agent: python-neutronclient
Content-Type: application/json
Accept: application/json
X-Auth-Token: c52a1b304fec4ca0ac85dc1741eec6e2

Response Parameters

Name

In

Type

Description

metering_label

body

object

A metering_label object.

description

body

string

A human-readable description for the resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

shared

body

boolean

Indicates whether this metering label is shared across all projects.

id

body

string

The ID of the metering label.

name

body

string

Human-readable name of the resource.

Response Example

{
    "metering_label": {
        "project_id": "45345b0ee1ea477fac0f541b2cb79cd4",
        "tenant_id": "45345b0ee1ea477fac0f541b2cb79cd4",
        "description": "label1 description",
        "name": "label1",
        "id": "a6700594-5b7a-4105-8bfe-723b346ce866",
        "shared": false
    }
}
DELETE
/v2.0/metering/metering-labels/{metering_label_id}

Delete metering label

Deletes an L3 metering label.

Normal response codes: 204

Error response codes: 401, 404

Request

Name

In

Type

Description

metering_label_id

path

string

The ID of the metering label.

Request Example

DELETE /v2.0/metering/metering-labels/a6700594-5b7a-4105-8bfe-723b346ce866 HTTP/1.1
Host: controlnode:9696
User-Agent: python-neutronclient
Content-Type: application/json
Accept: application/json
X-Auth-Token: c52a1b304fec4ca0ac85dc1741eec6e2

Response

There is no body content for the response of a successful DELETE request.

GET
/v2.0/metering/metering-label-rules

List metering label rules

Lists a summary of all L3 metering label rules that belong to the project.

The list shows the ID for each metering label rule.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

direction (Optional)

query

string

Filter the metering rule list result by the direction in which the metering rule is applied, which is ingress or egress.

remote_ip_prefix (Optional)

query

string

(deprecated) Filter the metering rule list result by the source IP prefix that the metering rule associates with. By source IP prefix, one should read the internal/private IPs used in OpenStack.

source_ip_prefix (Optional)

query

string

The source IP prefix that the metering rule is associated with; in this context, source IP prefix represents the source IP of the network packet. Therefore, for an ingress rule, the source IP is the IP of the system accessing something inside OpenStack. On the other hand, for an egress rule, the source IP is the internal IP associated with some OpenStack VM. Moreover, instead of an IP, one can also use a CIDR as the source IP prefix.

destination_ip_prefix (Optional)

query

string

The destination IP prefix that the metering rule is associated with; in this context, destination IP prefix represents the destination IP of the network packet. Therefore, for an ingress rule, the destination IP is the internal IP associated with some OpenStack VM. On the other hand, for an egress rule, the destination IP prefix is the IP of some external system that an application running inside some OpenStack virtual machine is trying to access. Moreover, instead of an IP, one can also use a CIDR as the destination IP prefix.

excluded (Optional)

query

boolean

Filter the metering rule list result based on whether the metering rule exclude the traffic of a specific IP address with the remote_ip_prefix value.

metering_label_id (Optional)

query

string

Filter the metering rule list result by the ID of the metering label associated with this metering rule.

id (Optional)

query

string

Filter the list result by the ID of the resource.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a metering label attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • id

  • metering_label_id

  • excluded

  • remote_ip_prefix

  • direction

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

metering_label_rules

body

array

A list of metering_label_rule objects.

direction

body

string

Ingress or egress, which is the direction in which the metering rule is applied.

remote_ip_prefix

body

string

(deprecated) The source IP prefix that is matched by this metering rule. By source IP prefix, one should read the internal/private IPs used in OpenStack.

source_ip_prefix (Optional)

query

string

The source IP prefix that the metering rule is associated with; in this context, source IP prefix represents the source IP of the network packet. Therefore, for an ingress rule, the source IP is the IP of the system accessing something inside OpenStack. On the other hand, for an egress rule, the source IP is the internal IP associated with some OpenStack VM. Moreover, instead of an IP, one can also use a CIDR as the source IP prefix.

destination_ip_prefix (Optional)

query

string

The destination IP prefix that the metering rule is associated with; in this context, destination IP prefix represents the destination IP of the network packet. Therefore, for an ingress rule, the destination IP is the internal IP associated with some OpenStack VM. On the other hand, for an egress rule, the destination IP prefix is the IP of some external system that an application running inside some OpenStack virtual machine is trying to access. Moreover, instead of an IP, one can also use a CIDR as the destination IP prefix.

excluded

body

boolean

Indicates whether to count the traffic of a specific IP address with the remote_ip_prefix, source_ip_prefix, or destination_ip_prefix values.

metering_label_id

body

string

The metering label ID associated with this metering rule.

id

body

string

The ID of the metering label rule.

Response Example

{
    "metering_label_rules": [
        {
            "remote_ip_prefix": "20.0.0.0/24",
            "direction": "ingress",
            "metering_label_id": "e131d186-b02d-4c0b-83d5-0c0725c4f812",
            "id": "9536641a-7d14-4dc5-afaf-93a973ce0eb8",
            "excluded": false
        },
        {
            "remote_ip_prefix": "10.0.0.0/24",
            "direction": "ingress",
            "metering_label_id": "e131d186-b02d-4c0b-83d5-0c0725c4f812",
            "id": "ffc6fd15-40de-4e7d-b617-34d3f7a93aec",
            "excluded": false
        }
    ]
}
POST
/v2.0/metering/metering-label-rules

Create metering label rule

Creates an L3 metering label rule.

Normal response codes: 201

Error response codes: 400, 401, 403, 404, 409

Request

Name

In

Type

Description

metering_label_rule

body

object

A metering_label_rule object.

remote_ip_prefix

body

string

(deprecated) The source IP prefix that is matched by this metering rule. By source IP prefix, one should read the internal/private IPs used in OpenStack.

source_ip_prefix (Optional)

query

string

The source IP prefix that the metering rule is associated with; in this context, source IP prefix represents the source IP of the network packet. Therefore, for an ingress rule, the source IP is the IP of the system accessing something inside OpenStack. On the other hand, for an egress rule, the source IP is the internal IP associated with some OpenStack VM. Moreover, instead of an IP, one can also use a CIDR as the source IP prefix.

destination_ip_prefix (Optional)

query

string

The destination IP prefix that the metering rule is associated with; in this context, destination IP prefix represents the destination IP of the network packet. Therefore, for an ingress rule, the destination IP is the internal IP associated with some OpenStack VM. On the other hand, for an egress rule, the destination IP prefix is the IP of some external system that an application running inside some OpenStack virtual machine is trying to access. Moreover, instead of an IP, one can also use a CIDR as the destination IP prefix.

direction

body

string

Ingress or egress, which is the direction in which the metering rule is applied.

metering_label_id

body

string

The metering label ID associated with this metering rule.

excluded (Optional)

body

boolean

Indicates whether to count the traffic of a specific IP address with the remote_ip_prefix, source_ip_prefix, or destination_ip_prefix values. Default is false.

Request Example

{
    "metering_label_rule": {
        "remote_ip_prefix": "10.0.1.0/24",
        "direction": "ingress",
        "metering_label_id": "e131d186-b02d-4c0b-83d5-0c0725c4f812"
    }
}

Response Parameters

Name

In

Type

Description

metering_label_rule

body

object

A metering_label_rule object.

direction

body

string

Ingress or egress, which is the direction in which the metering rule is applied.

remote_ip_prefix

body

string

(deprecated) The source IP prefix that is matched by this metering rule. By source IP prefix, one should read the internal/private IPs used in OpenStack.

source_ip_prefix (Optional)

query

string

The source IP prefix that the metering rule is associated with; in this context, source IP prefix represents the source IP of the network packet. Therefore, for an ingress rule, the source IP is the IP of the system accessing something inside OpenStack. On the other hand, for an egress rule, the source IP is the internal IP associated with some OpenStack VM. Moreover, instead of an IP, one can also use a CIDR as the source IP prefix.

destination_ip_prefix (Optional)

query

string

The destination IP prefix that the metering rule is associated with; in this context, destination IP prefix represents the destination IP of the network packet. Therefore, for an ingress rule, the destination IP is the internal IP associated with some OpenStack VM. On the other hand, for an egress rule, the destination IP prefix is the IP of some external system that an application running inside some OpenStack virtual machine is trying to access. Moreover, instead of an IP, one can also use a CIDR as the destination IP prefix.

excluded

body

boolean

Indicates whether to count the traffic of a specific IP address with the remote_ip_prefix, source_ip_prefix, or destination_ip_prefix values.

metering_label_id

body

string

The metering label ID associated with this metering rule.

id

body

string

The ID of the metering label rule.

Response Example

{
    "metering_label_rule": {
        "remote_ip_prefix": "10.0.1.0/24",
        "direction": "ingress",
        "metering_label_id": "e131d186-b02d-4c0b-83d5-0c0725c4f812",
        "id": "00e13b58-b4f2-4579-9c9c-7ac94615f9ae",
        "excluded": false
    }
}
GET
/v2.0/metering/metering-label-rules/{metering_label_rule_id}

Show metering label rule details

Shows details for a metering label rule.

The response body shows this information for each metering label rule:

  • direction. Either ingress or egress.

  • excluded. Either true or false.

  • The ID for the metering label rule.

  • The remote IP prefix (deprecated).

  • The source IP prefix

  • The destination IP prefix

  • The metering label ID for the metering label with which the rule is associated.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

metering_label_rule_id

path

string

The ID of the metering label rule.

Request Example

GET /v2.0/metering/metering-label-rules/9536641a-7d14-4dc5-afaf-93a973ce0eb8 HTTP/1.1
Host: controlnode:9696
User-Agent: python-neutronclient
Content-Type: application/json
Accept: application/json
X-Auth-Token: c52a1b304fec4ca0ac85dc1741eec6e2

Response Paramters

Name

In

Type

Description

metering_label_rule

body

object

A metering_label_rule object.

direction

body

string

Ingress or egress, which is the direction in which the metering rule is applied.

remote_ip_prefix

body

string

(deprecated) The source IP prefix that is matched by this metering rule. By source IP prefix, one should read the internal/private IPs used in OpenStack.

source_ip_prefix (Optional)

query

string

The source IP prefix that the metering rule is associated with; in this context, source IP prefix represents the source IP of the network packet. Therefore, for an ingress rule, the source IP is the IP of the system accessing something inside OpenStack. On the other hand, for an egress rule, the source IP is the internal IP associated with some OpenStack VM. Moreover, instead of an IP, one can also use a CIDR as the source IP prefix.

destination_ip_prefix (Optional)

query

string

The destination IP prefix that the metering rule is associated with; in this context, destination IP prefix represents the destination IP of the network packet. Therefore, for an ingress rule, the destination IP is the internal IP associated with some OpenStack VM. On the other hand, for an egress rule, the destination IP prefix is the IP of some external system that an application running inside some OpenStack virtual machine is trying to access. Moreover, instead of an IP, one can also use a CIDR as the destination IP prefix.

excluded

body

boolean

Indicates whether to count the traffic of a specific IP address with the remote_ip_prefix, source_ip_prefix, or destination_ip_prefix values.

metering_label_id

body

string

The metering label ID associated with this metering rule.

id

body

string

The ID of the metering label rule.

Response Example

{
    "metering_label_rule": {
        "remote_ip_prefix": "20.0.0.0/24",
        "direction": "ingress",
        "metering_label_id": "e131d186-b02d-4c0b-83d5-0c0725c4f812",
        "id": "9536641a-7d14-4dc5-afaf-93a973ce0eb8",
        "excluded": false
    }
}
DELETE
/v2.0/metering/metering-label-rules/{metering_label_rule_id}

Delete metering label rule

Deletes an L3 metering label rule.

Normal response codes: 204

Error response codes: 401, 404

Request

Name

In

Type

Description

metering_label_rule_id

path

string

The ID of the metering label rule.

Request Example

DELETE /v2.0/metering/metering-labels/37b31179-71ee-4f0a-b130-0eeb28e7ede7 HTTP/1.1
Host: controlnode:9696
User-Agent: python-neutronclient
Content-Type: application/json
Accept: application/json
X-Auth-Token: c52a1b304fec4ca0ac85dc1741eec6e2

Response

There is no body content for the response of a successful DELETE request.

Network IP availability and usage stats

The extension network-ip-availability allows users to list and show the network IP usage stats of all networks or of a specified network. By default policy configuration, only administrative users can use this API.

GET
/v2.0/network-ip-availabilities/{network_id}

Show Network IP Availability

Shows network IP availability details for a network.

By default policy configuration, only administrative users can retrieve IP availability. Otherwise, Not Found (404) will be returned.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

network_id

path

string

The ID of the network.

Response Parameters

Name

In

Type

Description

network_ip_availability

body

object

A network_ip_availability object.

network_id

body

string

The ID of the network whose IP availability detail is reported.

network_name

body

string

Human-readable name of the network.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

total_ips

body

integer

The total number of IP addresses in a network.

used_ips

body

integer

The number of used IP addresses of all subnets in a network.

subnet_ip_availability

body

array

A list of dictionaries showing subnet IP availability. It contains information for every subnet associated to the network.

subnet_id

body

string

The ID of the subnet whose IP availability detail is reported.

subnet_name

body

string

The name of the subnet.

ip_version

body

integer

The IP protocol version. Value is 4 or 6.

cidr

body

string

The CIDR of the subnet.

Response Example

{
    "network_ip_availability": {
        "used_ips": 4,
        "subnet_ip_availability": [
            {
                "used_ips": 2,
                "subnet_id": "44e70d00-80a2-4fb1-ab59-6190595ceb61",
                "subnet_name": "private-subnet",
                "ip_version": 4,
                "cidr": "10.0.0.0/24",
                "total_ips": 253
            },
            {
                "used_ips": 2,
                "subnet_id": "a90623df-00e1-4902-a675-40674385d74c",
                "subnet_name": "ipv6-private-subnet",
                "ip_version": 6,
                "cidr": "fdbf:ac66:9be8::/64",
                "total_ips": 18446744073709552000
            }
        ],
        "network_id": "6801d9c8-20e6-4b27-945d-62499f00002e",
        "project_id": "d56d3b8dd6894a508cf41b96b522328c",
        "tenant_id": "d56d3b8dd6894a508cf41b96b522328c",
        "total_ips": 18446744073709552000,
        "network_name": "private"
    }
}
GET
/v2.0/network-ip-availabilities

List Network IP Availability

Lists network IP availability of all networks.

By default policy configuration, only administrative users can retrieve IP availabilities. Otherwise, an empty list will be returned.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

network_id (Optional)

query

string

Filter the list result by the ID of the network whose IP availability detail is reported.

network_name (Optional)

query

string

Filter the list result by the human-readable name of the network.

tenant_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

project_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

ip_version (Optional)

query

integer

Filter the list result by the IP protocol version. Valid value is 4 or 6.

Response Parameters

Name

In

Type

Description

network_ip_availabilities

body

array

The network_ip_availabilities object.

network_id

body

string

The ID of the network whose IP availability detail is reported.

network_name

body

string

Human-readable name of the network.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

total_ips

body

integer

The total number of IP addresses in a network.

used_ips

body

integer

The number of used IP addresses of all subnets in a network.

subnet_ip_availability

body

array

A list of dictionaries showing subnet IP availability. It contains information for every subnet associated to the network.

subnet_id

body

string

The ID of the subnet whose IP availability detail is reported.

subnet_name

body

string

The name of the subnet.

ip_version

body

integer

The IP protocol version. Value is 4 or 6.

cidr

body

string

The CIDR of the subnet.

Response Example

{
    "network_ip_availabilities": [
        {
            "network_id": "4cf895c9-c3d1-489e-b02e-59b5c8976809",
            "network_name": "public",
            "subnet_ip_availability": [
                {
                    "cidr": "2001:db8::/64",
                    "ip_version": 6,
                    "subnet_id": "ca3f46c4-c6ff-4272-9be4-0466f84c6077",
                    "subnet_name": "ipv6-public-subnet",
                    "total_ips": 18446744073709552000,
                    "used_ips": 1
                },
                {
                    "cidr": "172.24.4.0/24",
                    "ip_version": 4,
                    "subnet_id": "cc02efc1-9d47-46bd-bab6-760919c836b5",
                    "subnet_name": "public-subnet",
                    "total_ips": 253,
                    "used_ips": 1
                }
            ],
            "project_id": "1a02cc95f1734fcc9d3c753818f03002",
            "tenant_id": "1a02cc95f1734fcc9d3c753818f03002",
            "total_ips": 253,
            "used_ips": 2
        },
        {
            "network_id": "6801d9c8-20e6-4b27-945d-62499f00002e",
            "network_name": "private",
            "subnet_ip_availability": [
                {
                    "cidr": "10.0.0.0/24",
                    "ip_version": 4,
                    "subnet_id": "44e70d00-80a2-4fb1-ab59-6190595ceb61",
                    "subnet_name": "private-subnet",
                    "total_ips": 253,
                    "used_ips": 2
                },
                {
                    "ip_version": 6,
                    "cidr": "fdbf:ac66:9be8::/64",
                    "subnet_id": "a90623df-00e1-4902-a675-40674385d74c",
                    "subnet_name": "ipv6-private-subnet",
                    "total_ips": 18446744073709552000,
                    "used_ips": 2
                }
            ],
            "project_id": "d56d3b8dd6894a508cf41b96b522328c",
            "tenant_id": "d56d3b8dd6894a508cf41b96b522328c",
            "total_ips": 18446744073709552000,
            "used_ips": 4
        }
    ]
}

Quotas extension (quotas)

Lists default quotas, current quotas for projects with non-default quota values, and shows, updates, and resets quotas for a project.

A quota value of -1 means that quota has no limit.

GET
/v2.0/quotas

List quotas for projects with non-default quota values

Lists quotas for projects with non-default quota values.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401, 403

Request

Response Parameters

Name

In

Type

Description

quotas

body

array

A list of quota objects.

floatingip

body

integer

The number of floating IP addresses allowed for each project. A value of -1 means no limit.

network

body

integer

The number of networks allowed for each project. A value of -1 means no limit.

port

body

integer

The number of ports allowed for each project. A value of -1 means no limit.

project_id

body

string

The ID of the project.

rbac_policy

body

integer

The number of role-based access control (RBAC) policies for each project. A value of -1 means no limit.

router

body

integer

The number of routers allowed for each project. A value of -1 means no limit.

security_group

body

integer

The number of security groups allowed for each project. A value of -1 means no limit.

security_group_rule

body

integer

The number of security group rules allowed for each project. A value of -1 means no limit.

subnet

body

integer

The number of subnets allowed for each project. A value of -1 means no limit.

subnetpool

body

integer

The number of subnet pools allowed for each project. A value of -1 means no limit.

tenant_id

body

string

The ID of the project.

Response Example

{
    "quotas": [
        {
            "floatingip": 50,
            "network": 15,
            "port": 50,
            "project_id": "bab7d5c60cd041a0a36f7c4b6e1dd978",
            "rbac_policy": -1,
            "router": 10,
            "security_group": 10,
            "security_group_rule": 100,
            "subnet": 10,
            "subnetpool": -1,
            "tenant_id": "bab7d5c60cd041a0a36f7c4b6e1dd978"
        }
    ]
}
GET
/v2.0/quotas/{project_id}

List quotas for a project

Lists quotas for a project.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401, 403

Request

Name

In

Type

Description

project_id

path

string

The ID of the project.

Response Parameters

Name

In

Type

Description

quota

body

object

A quota object.

floatingip

body

integer

The number of floating IP addresses allowed for each project. A value of -1 means no limit.

network

body

integer

The number of networks allowed for each project. A value of -1 means no limit.

port

body

integer

The number of ports allowed for each project. A value of -1 means no limit.

rbac_policy

body

integer

The number of role-based access control (RBAC) policies for each project. A value of -1 means no limit.

router

body

integer

The number of routers allowed for each project. A value of -1 means no limit.

security_group

body

integer

The number of security groups allowed for each project. A value of -1 means no limit.

security_group_rule

body

integer

The number of security group rules allowed for each project. A value of -1 means no limit.

subnet

body

integer

The number of subnets allowed for each project. A value of -1 means no limit.

subnetpool

body

integer

The number of subnet pools allowed for each project. A value of -1 means no limit.

Response Example

{
    "quota": {
        "floatingip": 50,
        "network": 10,
        "port": 50,
        "rbac_policy": -1,
        "router": 10,
        "security_group": 10,
        "security_group_rule": 100,
        "subnet": 10,
        "subnetpool": -1
    }
}
PUT
/v2.0/quotas/{project_id}

Update quota for a project

Updates quotas for a project. Use when non-default quotas are desired.

Normal response codes: 200

Error response codes: 401, 403

Request

Name

In

Type

Description

project_id

path

string

The ID of the project.

quota

body

object

A quota object.

floatingip (Optional)

body

integer

The number of floating IP addresses allowed for each project. A value of -1 means no limit.

network (Optional)

body

integer

The number of networks allowed for each project. A value of -1 means no limit.

port (Optional)

body

integer

The number of ports allowed for each project. A value of -1 means no limit.

rbac_policy (Optional)

body

integer

The number of role-based access control (RBAC) policies for each project. A value of -1 means no limit.

router (Optional)

body

integer

The number of routers allowed for each project. A value of -1 means no limit.

security_group (Optional)

body

integer

The number of security groups allowed for each project. A value of -1 means no limit.

security_group_rule (Optional)

body

integer

The number of security group rules allowed for each project. A value of -1 means no limit.

subnet (Optional)

body

integer

The number of subnets allowed for each project. A value of -1 means no limit.

subnetpool (Optional)

body

integer

The number of subnet pools allowed for each project. A value of -1 means no limit.

check_limit (Optional)

body

object

(deprecated) A flag used in the quota update command. If enabled, the Quota engine will first check the resource usage before applying the new quota limit.

force (Optional)

body

object

A flag used in the quota update command. If enabled, the Quota engine will not check the resource usage before applying the new quota limit.

Request Example

{
    "quota": {
        "floatingip": 50,
        "network": 10,
        "port": 50,
        "rbac_policy": -1,
        "router": 10,
        "security_group": 10,
        "security_group_rule": 100,
        "subnet": 10,
        "subnetpool": -1,
        "check_limit": "True",
        "force": "False"
    }
}

Response Parameters

Name

In

Type

Description

quota

body

object

A quota object.

floatingip

body

integer

The number of floating IP addresses allowed for each project. A value of -1 means no limit.

network

body

integer

The number of networks allowed for each project. A value of -1 means no limit.

port

body

integer

The number of ports allowed for each project. A value of -1 means no limit.

rbac_policy

body

integer

The number of role-based access control (RBAC) policies for each project. A value of -1 means no limit.

router

body

integer

The number of routers allowed for each project. A value of -1 means no limit.

security_group

body

integer

The number of security groups allowed for each project. A value of -1 means no limit.

security_group_rule

body

integer

The number of security group rules allowed for each project. A value of -1 means no limit.

subnet

body

integer

The number of subnets allowed for each project. A value of -1 means no limit.

subnetpool

body

integer

The number of subnet pools allowed for each project. A value of -1 means no limit.

Response Example

{
    "quota": {
        "subnet": 10,
        "network": 15,
        "floatingip": 50,
        "subnetpool": -1,
        "security_group_rule": 100,
        "security_group": 10,
        "router": 10,
        "rbac_policy": -1,
        "port": 50
    }
}
DELETE
/v2.0/quotas/{project_id}

Reset quota for a project

Resets quotas to default values for a project.

Normal response codes: 204

Error response codes: 401, 403, 404

Request

Name

In

Type

Description

project_id

path

string

The ID of the project.

Response

There is no body content for the response of a successful DELETE request.

GET
/v2.0/quotas/{project_id}/default

List default quotas for a project

Lists default quotas for a project.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401, 403

Request

Name

In

Type

Description

project_id

path

string

The ID of the project.

Response Parameters

Name

In

Type

Description

quota

body

object

A quota object.

floatingip

body

integer

The number of floating IP addresses allowed for each project. A value of -1 means no limit.

network

body

integer

The number of networks allowed for each project. A value of -1 means no limit.

port

body

integer

The number of ports allowed for each project. A value of -1 means no limit.

rbac_policy

body

integer

The number of role-based access control (RBAC) policies for each project. A value of -1 means no limit.

router

body

integer

The number of routers allowed for each project. A value of -1 means no limit.

security_group

body

integer

The number of security groups allowed for each project. A value of -1 means no limit.

security_group_rule

body

integer

The number of security group rules allowed for each project. A value of -1 means no limit.

subnet

body

integer

The number of subnets allowed for each project. A value of -1 means no limit.

subnetpool

body

integer

The number of subnet pools allowed for each project. A value of -1 means no limit.

Response Example

{
    "quota": {
        "floatingip": 50,
        "network": 10,
        "port": 50,
        "rbac_policy": -1,
        "router": 10,
        "security_group": 10,
        "security_group_rule": 100,
        "subnet": 10,
        "subnetpool": -1
    }
}

Quotas details extension (quota_details)

Extends the quotas API to show a quota set for each project that includes the quota’s used, limit and reserved counts per resource.

A quota value of -1 means that quota has no limit.

GET
/v2.0/quotas/{project_id}/details.json

Show quota details for a tenant

Shows quota details for a project.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 403

Request

Name

In

Type

Description

project_id

path

string

The ID of the project.

Response Parameters

Name

In

Type

Description

quota

body

object

A quota detail object. Each key in the object corresponds to a resource type (network, port, etc.) having a quota. The value for each resource type is itself an object (the quota set) containing the quota’s used, limit and reserved integer values.

Response Example

{
    "quota": {
        "rbac_policy": {
            "used": 4,
            "limit": 10,
            "reserved": 0
        },
        "subnetpool": {
            "used": 2,
            "limit": -1,
            "reserved": 0
        },
        "security_group_rule": {
            "used": 10,
            "limit": 100,
            "reserved": 1
        },
        "security_group": {
            "used": 3,
            "limit": 10,
            "reserved": 0
        },
        "subnet": {
            "used": 3,
            "limit": 100,
            "reserved": 0
        },
        "port": {
            "used": 21,
            "limit": 500,
            "reserved": 3
        },
        "network" :{
            "used": 9,
            "limit": 100,
            "reserved": 2
        }
    }
}

Service providers

Lists service providers.

GET
/v2.0/service-providers

List service providers

Lists service providers and their associated service types.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

service_providers

body

array

A list of service_provider objects.

service_type

body

string

The service type, which is CORE, DUMMY, FIREWALL, FLAVORS, L3_ROUTER_NAT, METERING, QOS, or VPN.

name

body

string

Human-readable name of the resource.

default

body

boolean

Defines whether the provider is the default for the service type. If this value is true, the provider is the default. If this value is false, the provider is not the default.

Response Example

{
    "service_providers": [
        {
            "service_type": "FIREWALL",
            "default": true,
            "name": "haproxy"
        }
    ]
}

Tag extension (tags)

Shows details for, updates, and deletes tags.

The maximum number of characters allowed in a tag is 60. If the length is longer than 60, the API returns the HTTP Bad Request (400) response code with ‘invalid input for operation’ error message.

Standard Attributes Tag Extension

The standard-attr-tag extends tagging support to some resources that support standard attributes. This includes networks, ports, subnets, subnet pools, floating IPs, routers, security groups, security group rules, QoS policies and trunks.

POST
/v2.0/{resource_type}/{resource_id}/tags

Create tags

Creates multiple tags for a resource.

Normal response codes: 200

Error response codes: 400, 401, 403

Request

Name

In

Type

Description

resource_type

path

string

The type of resource which the tag is set on.

resource_id

path

string

The ID of resource which the tag is set on.

tags

body

array

The list of tags on the resource.

Request Example

{
    "tags": [
        "red",
        "blue"
    ]
}
PUT
/v2.0/{resource_type}/{resource_id}/tags

Replace all tags

Replaces all tags on the resource.

Normal response codes: 200

Error response codes: 400, 401, 404

Request

Name

In

Type

Description

resource_type

path

string

The type of resource which the tag is set on.

resource_id

path

string

The ID of resource which the tag is set on.

tags

body

array

The list of tags on the resource.

Request Example

{
    "tags": [
        "red",
        "blue"
    ]
}

Response Parameters

Name

In

Type

Description

tags

body

array

The list of tags on the resource.

Response Example

{
    "tags": [
        "red",
        "blue"
    ]
}
DELETE
/v2.0/{resource_type}/{resource_id}/tags

Remove all tags

Removes all tags on the resource.

Normal response codes: 204

Error response codes: 401, 404

Request

Name

In

Type

Description

resource_type

path

string

The type of resource which the tag is set on.

resource_id

path

string

The ID of resource which the tag is set on.

Response

There is no body content for the response of a successful DELETE request.

GET
/v2.0/{resource_type}/{resource_id}/tags/{tag}

Confirm a tag

Confirms a given tag is set on the resource.

Normal response codes: 204

Error response codes: 401, 404

Request

Name

In

Type

Description

resource_type

path

string

The type of resource which the tag is set on.

resource_id

path

string

The ID of resource which the tag is set on.

tag

path

string

The name for the tag.

Response

There is no body content for the response of a successful GET request.

PUT
/v2.0/{resource_type}/{resource_id}/tags/{tag}

Add a tag

Adds a tag on the resource.

Normal response codes: 201

Error response codes: 401, 404

Request

Name

In

Type

Description

resource_type

path

string

The type of resource which the tag is set on.

resource_id

path

string

The ID of resource which the tag is set on.

tag

path

string

The name for the tag.

Response

There is no body content for the response of a successful PUT request.

GET
/v2.0/{resource_type}/{resource_id}/tags

Obtain Tag List

Obtains the tags for a resource.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

resource_type

path

string

The type of resource which the tag is set on.

resource_id

path

string

The ID of resource which the tag is set on.

Response

Name

In

Type

Description

tags

body

array

The list of tags on the resource.

Response Example

{
    "tags": [
        "red",
        "blue"
    ]
}
DELETE
/v2.0/{resource_type}/{resource_id}/tags/{tag}

Remove a tag

Removes a tag on the resource.

Normal response codes: 204

Error response codes: 401, 404

Request

Name

In

Type

Description

resource_type

path

string

The type of resource which the tag is set on.

resource_id

path

string

The ID of resource which the tag is set on.

tag

path

string

The name for the tag.

Response

There is no body content for the response of a successful DELETE request.

Quality of Service

QoS rule types

Lists and shows information for QoS rule types available in current deployment.

Rule type details

The qos-rule-type-details extension adds the drivers attribute to QoS rule types. The drivers attribute’s value is a list of driver objects. Each driver object represents a loaded backend QoS driver and includes the driver’s name as well as a list of its supported_parameters and acceptable values.

GET
/v2.0/qos/rule-types

List QoS rule types

Lists available qos rule types.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

all_supported (Optional)

body

boolean

Set to true to return all QoS rule types supported by any loaded driver.

all_rules (Optional)

body

boolean

Set to true to return all QoS rule types implemented in the Neutron server.

Response Parameters

Name

In

Type

Description

rule_types

body

array

A list of QoS rule_type objects.

type

body

string

The type of QoS rule.

Response Example

{
    "rule_types": [
        {
            "type": "bandwidth_limit"
        },
        {
            "type": "dscp_marking"
        },
        {
            "type": "minimum_bandwidth"
        }
    ]
}
GET
/v2.0/qos/rule-types/{rule_type}

Show QoS rule type details

Shows details for an available QoS rule type.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

rule_type

path

string

The name of the QoS rule type. It should be one of the types returned by the List QoS rule types API, for example bandwidth_limit or dscp_marking.

Response Parameters

Name

In

Type

Description

type

body

string

The type of QoS rule.

drivers

body

list

List of loaded QoS drivers with supported rule type parameters with possible values for each. Each driver is represented by a dict with the keys name and supported_parameters. Field name contains the name of a backend driver. Field supported_parameters contains a list of dicts with parameter_name, parameter_type and parameter_values fields. The valid values for parameter_type are choices or range. If parameter_type is choices then parameter_values contains a list of acceptable values, otherwise it contains a dict with keys of start and end which define the range of acceptable values.

Response Example (type “bandwidth_limit”)

{
    "drivers": [
        {
            "name": "openvswitch",
            "supported_parameters": [
                {
                    "parameter_name": "max_kbps",
                    "parameter_type": "range",
                    "parameter_values": {
                        "end": 2147483647,
                        "start": 0
                    }
                },
                {
                    "parameter_name": "direction",
                    "parameter_type": "choices",
                    "parameter_values": [
                        "ingress",
                        "egress"
                    ]
                },
                {
                    "parameter_name": "max_burst_kbps",
                    "parameter_type": "range",
                    "parameter_values": {
                        "end": 2147483647,
                        "start": 0
                    }
                }
            ]
        },
        {
            "name": "linuxbridge",
            "supported_parameters": [
                {
                    "parameter_name": "max_kbps",
                    "parameter_type": "range",
                    "parameter_values": {
                        "end": 2147483647,
                        "start": 0
                    }
                },
                {
                    "parameter_name": "direction",
                    "parameter_type": "choices",
                    "parameter_values": [
                        "ingress",
                        "egress"
                    ]
                },
                {
                    "parameter_name": "max_burst_kbps",
                    "parameter_type": "range",
                    "parameter_values": {
                        "end": 2147483647,
                        "start": 0
                    }
                }
            ]
        }
    ],
    "type": "bandwidth_limit"
}

Response Example (type “dscp_marking”)

{
    "drivers": [
        {
            "name": "openvswitch",
            "supported_parameters": [
                {
                    "parameter_name": "dscp_mark",
                    "parameter_type": "choices",
                    "parameter_values": [
                        0, 8, 10, 12, 14, 16, 18, 20, 22, 24, 26, 28, 30, 32, 34, 36, 38, 40, 44, 46, 48, 56
                    ]
                }
            ]
        },
        {
            "name": "linuxbridge",
            "supported_parameters": [
                {
                    "parameter_name": "dscp_mark",
                    "parameter_type": "choices",
                    "parameter_values": [
                        0, 8, 10, 12, 14, 16, 18, 20, 22, 24, 26, 28, 30, 32, 34, 36, 38, 40, 44, 46, 48, 56
                    ]
                }
            ]
        }
    ],
    "type": "dscp_marking"
}

QoS policies (qos)

Lists, creates, deletes, shows information for, and updates QoS policies.

Resource timestamps extension

The standard-attr-timestamp extension adds the created_at and updated_at attributes to all resources that have standard attributes.

QoS default extension

The QoS default extension (qos-default) allows a per project default QoS policy by adding the is_default attribute to policy resources.

Tag extension

The standard-attr-tag adds Tag support for resources with standard attributes by adding the tags attribute allowing consumers to associate tags with resources.

GET
/v2.0/qos/policies

List QoS policies

Lists all QoS policies associated with your project. One policy can contain more than one rule type.

The list might be empty.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

description (Optional)

query

string

Filter the list result by the human-readable description of the resource.

tenant_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

project_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

revision_number (Optional)

query

integer

Filter the list result by the revision number of the resource.

shared (Optional)

query

boolean

Filter the QoS policy list result based on whether this policy is shared across all projects.

id (Optional)

query

string

Filter the list result by the ID of the resource.

is_default (Optional)

query

boolean

Filter the QoS policy list result based on whether this policy is the default policy.

name (Optional)

query

string

Filter the list result by the human-readable name of the resource.

tags (Optional)

query

string

A list of tags to filter the list result by. Resources that match all tags in this list will be returned. Tags in query must be separated by comma.

tags-any (Optional)

query

string

A list of tags to filter the list result by. Resources that match any tag in this list will be returned. Tags in query must be separated by comma.

not-tags (Optional)

query

string

A list of tags to filter the list result by. Resources that match all tags in this list will be excluded. Tags in query must be separated by comma.

not-tags-any (Optional)

query

string

A list of tags to filter the list result by. Resources that match any tag in this list will be excluded. Tags in query must be separated by comma.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a QOS policy attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • id

  • name

  • project_id

  • tenant_id

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

policies

body

array

A list of QoS policy objects.

description

body

string

A human-readable description for the resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

revision_number

body

integer

The revision number of the resource.

shared

body

boolean

Indicates whether this policy is shared across all projects.

id

body

string

The ID of the QoS policy.

is_default

body

boolean

If true, the QoS policy is the default policy.

rules

body

array

A set of zero or more policy rules.

name

body

string

Human-readable name of the resource.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

tags

body

array

The list of tags on the resource.

Response Example

{
    "policies": [
        {
            "project_id": "8d4c70a21fed4aeba121a1a429ba0d04",
            "tenant_id": "8d4c70a21fed4aeba121a1a429ba0d04",
            "id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
            "is_default": false,
            "name": "10Mbit",
            "description": "This policy limits the ports to 10Mbit max.",
            "revision_number": 3,
            "created_at": "2018-04-03T21:26:39Z",
            "updated_at": "2018-04-03T21:26:39Z",
            "shared": false,
            "rules": [
                {
                    "max_kbps": 10000,
                    "type": "bandwidth_limit",
                    "id": "b1866696-032a-4228-857f-846075f63487",
                    "max_burst_kbps": 0,
                    "qos_policy_id": "46ebaec0-0570-43ac-82f6-60d2b03168c4"
                },
                {
                    "dscp_mark": 20,
                    "type": "dscp_marking",
                    "id": "d9c021d5-5433-4d7c-8bfa-69cca486aac8",
                    "qos_policy_id": "46ebaec0-0570-43ac-82f6-60d2b03168c4"
                }
            ],
            "tags": ["tag1,tag2"]
        }
    ]
}
POST
/v2.0/qos/policies

Create QoS policy

Creates a QoS policy.

Creates a QoS policy by using the configuration that you define in the request object. A response object is returned. The object contains a unique ID.

By the default policy configuration, if the caller is not an administrative user, this call returns the HTTP Forbidden (403) response code.

Users with an administrative role can create policies on behalf of other projects by specifying a project ID that is different than their own.

Normal response codes: 201

Error response codes: 401, 403, 404, 409

Request

Name

In

Type

Description

policy

body

object

A QoS policy object.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

tenant_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

project_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

shared (Optional)

body

boolean

Set to true to share this policy with other projects. Default is false.

is_default (Optional)

body

boolean

If true, the QoS policy is the default policy.

name (Optional)

body

string

Human-readable name of the resource.

Request Example

{
    "policy": {
        "name": "10Mbit",
        "description": "This policy limits the ports to 10Mbit max.",
        "shared": false
    }
}

Response Parameters

Name

In

Type

Description

policy

body

object

A QoS policy object.

description

body

string

A human-readable description for the resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

revision_number

body

integer

The revision number of the resource.

shared

body

boolean

Indicates whether this policy is shared across all projects.

rules

body

array

A set of zero or more policy rules.

id

body

string

The ID of the QoS policy.

is_default

body

boolean

If true, the QoS policy is the default policy.

name

body

string

Human-readable name of the resource.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

Response Example

{
    "policy": {
        "name": "10Mbit",
        "description": "This policy limits the ports to 10Mbit max.",
        "rules": [],
        "id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
        "is_default": false,
        "project_id": "8d4c70a21fed4aeba121a1a429ba0d04",
        "revision_number": 1,
        "tenant_id": "8d4c70a21fed4aeba121a1a429ba0d04",
        "created_at": "2018-04-03T21:26:39Z",
        "updated_at": "2018-04-03T21:26:39Z",
        "shared": false,
        "tags": ["tag1,tag2"]
    }
}
GET
/v2.0/qos/policies/{policy_id}

Show QoS policy details

Shows details for a QoS policy. One policy can contain more than one rule type.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

Response Parameters

Name

In

Type

Description

policy

body

object

A QoS policy object.

description

body

string

A human-readable description for the resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

revision_number

body

integer

The revision number of the resource.

shared

body

boolean

Indicates whether this policy is shared across all projects.

rules

body

array

A set of zero or more policy rules.

id

body

string

The ID of the QoS policy.

is_default

body

boolean

If true, the QoS policy is the default policy.

name

body

string

Human-readable name of the resource.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

Response Example

{
    "policy": {
        "project_id": "8d4c70a21fed4aeba121a1a429ba0d04",
        "tenant_id": "8d4c70a21fed4aeba121a1a429ba0d04",
        "id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
        "is_default": false,
        "name": "10Mbit",
        "description": "This policy limits the ports to 10Mbit max.",
        "revision_number": 3,
        "created_at": "2018-04-03T21:26:39Z",
        "updated_at": "2018-04-03T21:26:39Z",
        "shared": false,
        "rules": [
            {
                "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c793",
                "qos_policy_id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
                "max_kbps": 10000,
                "max_burst_kbps": 0,
                "type": "bandwidth_limit"
             },
            {
                "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c794",
                "qos_policy_id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
                "dscp_mark": 26,
                "type": "dscp_marking"
            }
        ],
        "tags": ["tag1,tag2"]
    }
}
PUT
/v2.0/qos/policies/{policy_id}

Update QoS policy

Updates a QoS policy.

Normal response codes: 200

Error response codes: 400, 401, 404, 412

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

policy

body

object

A QoS policy object.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

is_default (Optional)

body

boolean

If true, the QoS policy is the default policy.

shared (Optional)

body

boolean

Set to true to share this policy with other projects. Default is false.

name (Optional)

body

string

Human-readable name of the resource.

Request Example

{
    "policy": {
        "name": "10Mbit",
        "description": "This policy limits the ports to 10Mbit max.",
        "shared": false
    }
}

Response Parameters

Name

In

Type

Description

policy

body

object

A QoS policy object.

description

body

string

A human-readable description for the resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

revision_number

body

integer

The revision number of the resource.

shared

body

boolean

Indicates whether this policy is shared across all projects.

id

body

string

The ID of the QoS policy.

is_default

body

boolean

If true, the QoS policy is the default policy.

rules

body

array

A set of zero or more policy rules.

name

body

string

Human-readable name of the resource.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

Response Example

{
    "policy": {
        "name": "10Mbit",
        "description": "This policy limits the ports to 10Mbit max.",
        "id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
        "is_default": false,
        "project_id": "8d4c70a21fed4aeba121a1a429ba0d04",
        "revision_number": 3,
        "created_at": "2018-04-03T21:26:39Z",
        "updated_at": "2018-04-03T21:26:39Z",
        "tenant_id": "8d4c70a21fed4aeba121a1a429ba0d04",
        "shared": false,
        "tags": ["tag1,tag2"]
    }
}
DELETE
/v2.0/qos/policies/{policy_id}

Delete QoS policy

Deletes a QoS policy.

Normal response codes: 204

Error response codes: 400, 401, 404, 412

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

Response

There is no body content for the response of a successful DELETE request.

QoS bandwidth limit rules

Lists, creates, deletes, shows information for, and updates QoS bandwidth limit rules.

Bandwidth limit direction

The qos-bw-limit-direction extension adds the direction attribute to QoS rule types. The direction attribute allows to configure QoS bandwidth limit rule with specific direction: ingress or egress. Default is egress.

GET
/v2.0/qos/policies/{policy_id}/bandwidth_limit_rules

List bandwidth limit rules for QoS policy

Lists all bandwidth limit rules for a QoS policy.

The list might be empty.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

max_kbps (Optional)

query

integer

Filter the list result by the maximum KBPS (kilobits per second) value.

id (Optional)

query

string

Filter the list result by the ID of the resource.

max_burst_kbps (Optional)

query

integer

Filter the list result by the maximum burst size (in kilobits).

direction (Optional)

query

string

Filter the list result by the direction of the traffic to which the QoS rule is applied. Valid values are egress and ingress.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a bandwidth limit rule attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • direction

  • id

  • max_burst_kbps

  • max_kbps

Response Parameters

Name

In

Type

Description

bandwidth_limit_rules

body

array

A list of bandwidth limit rules associated with the QoS policy.

max_kbps

body

integer

The maximum KBPS (kilobits per second) value. If you specify this value, must be greater than 0 otherwise max_kbps will have no value.

id

body

string

The ID of the QoS Bandwidth limit rule.

max_burst_kbps

body

integer

The maximum burst size (in kilobits).

direction

body

string

The direction of the traffic to which the QoS rule is applied, as seen from the point of view of the port. Valid values are egress and ingress. Default value is egress.

tags

body

array

The list of tags on the resource.

Response Example

{
    "bandwidth_limit_rules": [
        {
            "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c793",
            "max_kbps": 10000,
            "max_burst_kbps": 0,
            "direction": "egress"
        }
    ]
}
POST
/v2.0/qos/policies/{policy_id}/bandwidth_limit_rules

Create bandwidth limit rule

Creates a bandwidth limit rule for a QoS policy.

Normal response codes: 201

Error response codes: 400, 401, 404, 409

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

bandwidth_limit_rule

body

object

A bandwidth_limit_rule object.

max_kbps (Optional)

body

integer

The maximum KBPS (kilobits per second) value. If you specify this value, must be greater than 0 otherwise max_kbps will have no value.

max_burst_kbps (Optional)

body

integer

The maximum burst size (in kilobits). Default is 0.

direction (Optional)

body

string

The direction of the traffic to which the QoS rule is applied, as seen from the point of view of the port. Valid values are egress and ingress. Default value is egress.

Request Example

{
    "bandwidth_limit_rule": {
        "max_kbps": "10000"
    }
}

Response Parameters

Name

In

Type

Description

bandwidth_limit_rule

body

object

A bandwidth_limit_rule object.

max_kbps

body

integer

The maximum KBPS (kilobits per second) value. If you specify this value, must be greater than 0 otherwise max_kbps will have no value.

id

body

string

The ID of the QoS Bandwidth limit rule.

max_burst_kbps

body

integer

The maximum burst size (in kilobits).

direction

body

string

The direction of the traffic to which the QoS rule is applied, as seen from the point of view of the port. Valid values are egress and ingress. Default value is egress.

tags

body

array

The list of tags on the resource.

Response Example

{
    "bandwidth_limit_rule": {
        "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c793",
        "max_kbps": 10000,
        "max_burst_kbps": 0,
        "direction": "egress"
    }
}
GET
/v2.0/qos/policies/{policy_id}/bandwidth_limit_rules/{rule_id}

Show bandwidth limit rule details

Shows details for a bandwidth limit rule for a QoS policy.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

rule_id

path

string

The ID of the QoS rule.

Response Parameters

Name

In

Type

Description

bandwidth_limit_rule

body

object

A bandwidth_limit_rule object.

max_kbps

body

integer

The maximum KBPS (kilobits per second) value. If you specify this value, must be greater than 0 otherwise max_kbps will have no value.

id

body

string

The ID of the QoS Bandwidth limit rule.

max_burst_kbps

body

integer

The maximum burst size (in kilobits).

direction

body

string

The direction of the traffic to which the QoS rule is applied, as seen from the point of view of the port. Valid values are egress and ingress. Default value is egress.

tags

body

array

The list of tags on the resource.

Response Example

{
    "bandwidth_limit_rule": {
        "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c793",
        "max_kbps": 10000,
        "max_burst_kbps": 0,
        "direction": "egress"
    }
}
PUT
/v2.0/qos/policies/{policy_id}/bandwidth_limit_rules/{rule_id}

Update bandwidth limit rule

Updates a bandwidth limit rule for a QoS policy.

Normal response codes: 200

Error response codes: 400, 401, 404

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

rule_id

path

string

The ID of the QoS rule.

bandwidth_limit_rule

body

object

A bandwidth_limit_rule object.

max_kbps (Optional)

body

integer

The maximum KBPS (kilobits per second) value. If you specify this value, must be greater than 0 otherwise max_kbps will have no value.

max_burst_kbps (Optional)

body

integer

The maximum burst size (in kilobits). Default is 0.

direction (Optional)

body

string

The direction of the traffic to which the QoS rule is applied, as seen from the point of view of the port. Valid values are egress and ingress.

Request Example

{
    "bandwidth_limit_rule": {
        "max_kbps": "10000"
    }
}

Response Parameters

Name

In

Type

Description

bandwidth_limit_rule

body

object

A bandwidth_limit_rule object.

max_kbps

body

integer

The maximum KBPS (kilobits per second) value. If you specify this value, must be greater than 0 otherwise max_kbps will have no value.

id

body

string

The ID of the QoS Bandwidth limit rule.

max_burst_kbps

body

integer

The maximum burst size (in kilobits).

direction

body

string

The direction of the traffic to which the QoS rule is applied, as seen from the point of view of the port. Valid values are egress and ingress.

tags

body

array

The list of tags on the resource.

Response Example

{
    "bandwidth_limit_rule": {
        "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c793",
        "max_kbps": 10000,
        "max_burst_kbps": 0,
        "direction": "egress"
    }
}
DELETE
/v2.0/qos/policies/{policy_id}/bandwidth_limit_rules/{rule_id}

Delete bandwidth limit rule

Deletes a bandwidth limit rule for a QoS policy.

Normal response codes: 204

Error response codes: 400, 401, 404

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

rule_id

path

string

The ID of the QoS rule.

Response

There is no body content for the response of a successful DELETE request.

QoS DSCP marking rules

Lists, creates, deletes, shows information for, and updates QoS DSCP marking rules.

GET
/v2.0/qos/policies/{policy_id}/dscp_marking_rules

List DSCP marking rules for QoS policy

Lists all DSCP marking rules for a QoS policy.

The list may be empty.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

dscp_mark (Optional)

query

integer

Filter the list result by the DSCP mark value.

id (Optional)

query

string

Filter the list result by the ID of the resource.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a DSCP marking rule attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • dscp_mark

  • id

Response Parameters

Name

In

Type

Description

dscp_marking_rules

body

array

A list of dscp_marking_rule objects.

dscp_mark

body

integer

The DSCP mark value.

id

body

string

The ID of the QoS DSCP marking rule.

tags

body

array

The list of tags on the resource.

Response Example

{
    "dscp_marking_rules": [
        {
            "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c794",
            "dscp_mark": 26
        }
    ]
}
POST
/v2.0/qos/policies/{policy_id}/dscp_marking_rules

Create DSCP marking rule

Creates a DSCP marking rule for a QoS policy.

Normal response codes: 201

Error response codes: 400, 401, 404, 409

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

dscp_marking_rule

body

object

A dscp_marking_rule object.

dscp_mark (Optional)

body

integer

The DSCP mark value.

Request Example

{
    "dscp_marking_rule": {
        "dscp_mark": "26"
    }
}

Response Parameters

Name

In

Type

Description

dscp_marking_rule

body

object

A dscp_marking_rule object.

dscp_mark

body

integer

The DSCP mark value.

id

body

string

The ID of the QoS DSCP marking rule.

tags

body

array

The list of tags on the resource.

Response Example

{
    "dscp_marking_rule": {
        "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c794",
        "dscp_mark": 26
    }
}
GET
/v2.0/qos/policies/{policy_id}/dscp_marking_rules/{dscp_rule_id}

Show DSCP marking rule details

Shows details for a DSCP marking rule for a QoS policy.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

dscp_rule_id

path

string

The ID of the DSCP rule.

Response Parameters

Name

In

Type

Description

dscp_marking_rule

body

object

A dscp_marking_rule object.

dscp_mark (Optional)

body

integer

The DSCP mark value.

id

body

string

The ID of the QoS DSCP marking rule.

tags

body

array

The list of tags on the resource.

Response Example

{
    "dscp_marking_rule": {
        "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c794",
        "dscp_mark": 26
    }
}
PUT
/v2.0/qos/policies/{policy_id}/dscp_marking_rules/{dscp_rule_id}

Update DSCP marking rule

Updates a DSCP marking rule for a QoS policy.

Normal response codes: 200

Error response codes: 400, 401, 404

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

dscp_rule_id

path

string

The ID of the DSCP rule.

dscp_marking_rule

body

object

A dscp_marking_rule object.

dscp_mark (Optional)

body

integer

The DSCP mark value.

Request Example

{
    "dscp_marking_rule": {
        "dscp_mark": "16"
    }
}

Response Parameters

Name

In

Type

Description

dscp_marking_rule

body

object

A dscp_marking_rule object.

dscp_mark

body

integer

The DSCP mark value.

id

body

string

The ID of the QoS DSCP marking rule.

tags

body

array

The list of tags on the resource.

Response Example

{
    "dscp_marking_rule": {
        "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c794",
        "dscp_mark": 16
    }
}
DELETE
/v2.0/qos/policies/{policy_id}/dscp_marking_rules/{dscp_rule_id}

Delete DSCP marking rule

Deletes a DSCP marking rule for a QoS policy.

Normal response codes: 204

Error response codes: 400, 401, 404

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

dscp_rule_id

path

string

The ID of the DSCP rule.

Response

There is no body content for the response of a successful DELETE request.

QoS minimum bandwidth rules

Lists, creates, deletes, shows information for, and updates QoS minimum bandwidth rules.

GET
/v2.0/qos/policies/{policy_id}/minimum_bandwidth_rules

List minimum bandwidth rules for QoS policy

Lists all minimum bandwidth rules for a QoS policy.

The list might be empty.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

min_kbps (Optional)

query

integer

Filter the list result by the minimum KBPS (kilobits per second) value which should be available for port.

id (Optional)

query

string

Filter the list result by the ID of the resource.

direction (Optional)

query

string

Filter the list result by the direction of the traffic to which the QoS rule is applied. Valid values are egress and ingress.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a minimum bandwidth rule attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • direction

  • id

  • min_kbps

Response Parameters

Name

In

Type

Description

minimum_bandwidth_rules

body

array

A list of minimum_bandwidth_rule objects associated with the QoS policy.

min_kbps

body

integer

The minimum KBPS (kilobits per second) value which should be available for port.

id

body

string

The ID of the QoS minimum bandwidth rule.

direction

body

string

The direction of the traffic to which the QoS rule is applied, as seen from the point of view of the port. Valid values are egress and ingress. Default value is egress.

tags

body

array

The list of tags on the resource.

Response Example

{
    "minimum_bandwidth_rules": [
        {
            "id": "1eddf7af-0b4c-42c5-8ae1-390b32f1de08",
            "min_kbps": 10000,
            "direction": "egress"
        }
    ]
}
POST
/v2.0/qos/policies/{policy_id}/minimum_bandwidth_rules

Create minimum bandwidth rule

Creates a minimum bandwidth rule for a QoS policy.

Normal response codes: 201

Error response codes: 400, 401, 404, 409

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

minimum_bandwidth_rule

body

object

A minimum_bandwidth_rule object.

min_kbps

body

integer

The minimum KBPS (kilobits per second) value which should be available for port.

direction (Optional)

body

string

The direction of the traffic to which the QoS rule is applied, as seen from the point of view of the port. Valid values are egress and ingress. Default value is egress.

Request Example

{
    "minimum_bandwidth_rule": {
        "min_kbps": "10000"
    }
}

Response Parameters

Name

In

Type

Description

minimum_bandwidth_rule

body

object

A minimum_bandwidth_rule object.

min_kbps

body

integer

The minimum KBPS (kilobits per second) value which should be available for port.

id

body

string

The ID of the QoS minimum bandwidth rule.

direction

body

string

The direction of the traffic to which the QoS rule is applied, as seen from the point of view of the port. Valid values are egress and ingress. Default value is egress.

tags

body

array

The list of tags on the resource.

Response Example

{
    "minimum_bandwidth_rule": {
        "id": "1eddf7af-0b4c-42c5-8ae1-390b32f1de08",
        "min_kbps": 10000,
        "direction": "egress"
    }
}
GET
/v2.0/qos/policies/{policy_id}/minimum_bandwidth_rules/{rule_id}

Show minimum bandwidth rule details

Shows details for a minimum bandwidth rule for a QoS policy.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

rule_id

path

string

The ID of the QoS rule.

Response Parameters

Name

In

Type

Description

minimum_bandwidth_rule

body

object

A minimum_bandwidth_rule object.

min_kbps

body

integer

The minimum KBPS (kilobits per second) value which should be available for port.

id

body

string

The ID of the QoS minimum bandwidth rule.

direction

body

string

The direction of the traffic to which the QoS rule is applied, as seen from the point of view of the port. Valid values are egress and ingress. Default value is egress.

tags

body

array

The list of tags on the resource.

Response Example

{
    "minimum_bandwidth_rule": {
        "id": "1eddf7af-0b4c-42c5-8ae1-390b32f1de08",
        "min_kbps": 10000,
        "direction": "egress"
    }
}
PUT
/v2.0/qos/policies/{policy_id}/minimum_bandwidth_rules/{rule_id}

Update minimum bandwidth rule

Updates a minimum bandwidth rule for a QoS policy.

Note that the rule cannot be updated, and the update is rejected with error code 501, if there is any bound port referring to the rule via the qos policy.

Normal response codes: 200

Error response codes: 400, 401, 404, 501

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

rule_id

path

string

The ID of the QoS rule.

minimum_bandwidth_rule

body

object

A minimum_bandwidth_rule object.

min_kbps

body

integer

The minimum KBPS (kilobits per second) value which should be available for port.

direction (Optional)

body

string

The direction of the traffic to which the QoS rule is applied, as seen from the point of view of the port. Valid values are egress and ingress.

Request Example

{
    "minimum_bandwidth_rule": {
        "min_kbps": "20000"
    }
}

Response Parameters

Name

In

Type

Description

minimum_bandwidth_rule

body

object

A minimum_bandwidth_rule object.

min_kbps

body

integer

The minimum KBPS (kilobits per second) value which should be available for port.

id

body

string

The ID of the QoS minimum bandwidth rule.

direction

body

string

The direction of the traffic to which the QoS rule is applied, as seen from the point of view of the port. Valid values are egress and ingress.

tags

body

array

The list of tags on the resource.

Response Example

{
    "minimum_bandwidth_rule": {
        "id": "1eddf7af-0b4c-42c5-8ae1-390b32f1de08",
        "min_kbps": 20000,
        "direction": "egress"
    }
}
DELETE
/v2.0/qos/policies/{policy_id}/minimum_bandwidth_rules/{rule_id}

Delete minimum bandwidth rule

Deletes a minimum bandwidth rule for a QoS policy.

Normal response codes: 204

Error response codes: 400, 401, 404

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

rule_id

path

string

The ID of the QoS rule.

Response

There is no body content for the response of a successful DELETE request.

QoS minimum packet rate rules

Lists, creates, deletes, shows information for, and updates QoS minimum packet rate rules.

GET
/v2.0/qos/policies/{policy_id}/minimum_packet_rate_rules

List minimum packet rate rules for QoS policy

Lists all minimum packet rate rules for a QoS policy.

The list might be empty.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

min_kpps (Optional)

query

integer

Filter the list result by the min kpps (kilo packets per second) value.

id (Optional)

query

string

Filter the list result by the ID of the resource.

direction (Optional)

query

string

Filter the list result by the direction of the traffic to which the QoS minimum packet rule is applied. Valid values are any, egress and ingress.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a minimum packet rate rule attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • direction

  • id

  • min_kpps

Response Parameters

Name

In

Type

Description

minimum_packet_rate_rules

body

array

A list of minimum_packet_rate_rule objects associated with the QoS policy.

min_kpps

body

integer

The minimum kilo (1000) packets per second (kpps) value.

id

body

string

The ID of the QoS minimum packet rate rule.

direction

body

string

The direction of the traffic to which the QoS minimum packet rate rule is applied, as seen from the point of view of the port. Valid values are any, egress and ingress.

tags

body

array

The list of tags on the resource.

Response Example

{
    "minimum_packet_rate_rules": [
        {
            "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c793",
            "min_kpps": 1000,
            "direction": "egress"
        }
    ]
  }
POST
/v2.0/qos/policies/{policy_id}/minimum_packet_rate_rules

Create minimum packet rate rule

Creates a minimum packet rate rule for a QoS policy.

Normal response codes: 201

Error response codes: 400, 401, 404, 409

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

minimum_packet_rate_rule

body

object

A minimum_packet_rate_rule object.

min_kpps

body

integer

The minimum kilo (1000) packets per second (kpps) value.

direction

body

string

The direction of the traffic to which the QoS minimum packet rate rule is applied, as seen from the point of view of the port. Valid values are any, egress and ingress.

Request Example

{
    "minimum_packet_rate_rule": {
        "min_kpps": 1000,
        "direction": "any"
    }
}

Response Parameters

Name

In

Type

Description

minimum_packet_rate_rule

body

object

A minimum_packet_rate_rule object.

min_kpps

body

integer

The minimum kilo (1000) packets per second (kpps) value.

id

body

string

The ID of the QoS minimum packet rate rule.

direction

body

string

The direction of the traffic to which the QoS minimum packet rate rule is applied, as seen from the point of view of the port. Valid values are any, egress and ingress.

tags

body

array

The list of tags on the resource.

Response Example

{
    "minimum_packet_rate_rule": {
        "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c793",
        "min_kpps": 1000,
        "direction": "any"
    }
}
GET
/v2.0/qos/policies/{policy_id}/minimum_packet_rate_rules/{rule_id}

Show minimum packet rate rule details

Shows details for a minimum packet rate rule for a QoS policy.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

rule_id

path

string

The ID of the QoS rule.

Response Parameters

Name

In

Type

Description

minimum_packet_rate_rule

body

object

A minimum_packet_rate_rule object.

min_kpps

body

integer

The minimum kilo (1000) packets per second (kpps) value.

id

body

string

The ID of the QoS minimum packet rate rule.

direction

body

string

The direction of the traffic to which the QoS minimum packet rate rule is applied, as seen from the point of view of the port. Valid values are any, egress and ingress.

tags

body

array

The list of tags on the resource.

Response Example

{
    "minimum_packet_rate_rule": {
        "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c793",
        "min_kpps": 1000,
        "direction": "egress"
    }
}
PUT
/v2.0/qos/policies/{policy_id}/minimum_packet_rate_rules/{rule_id}

Update minimum packet rate rule

Updates a minimum packet rate rule for a QoS policy.

Note that the rule cannot be updated, and the update is rejected with error code 501, if there is any bound port referring to the rule via the qos policy.

Normal response codes: 200

Error response codes: 400, 401, 404, 409, 501

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

rule_id

path

string

The ID of the QoS rule.

minimum_packet_rate_rule

body

object

A minimum_packet_rate_rule object.

min_kpps (Optional)

body

integer

The minimum kilo (1000) packets per second (kpps) value.

direction (Optional)

body

string

The direction of the traffic to which the QoS minimum packet rate rule is applied, as seen from the point of view of the port. Valid values are any, egress and ingress.

Request Example

{
    "minimum_packet_rate_rule": {
        "min_kpps": 2000,
        "direction": "any"
    }
}

Response Parameters

Name

In

Type

Description

minimum_packet_rate_rule

body

object

A minimum_packet_rate_rule object.

min_kpps

body

integer

The minimum kilo (1000) packets per second (kpps) value.

id

body

string

The ID of the QoS minimum packet rate rule.

direction

body

string

The direction of the traffic to which the QoS minimum packet rate rule is applied, as seen from the point of view of the port. Valid values are any, egress and ingress.

tags

body

array

The list of tags on the resource.

Response Example

{
    "minimum_packet_rate_rule": {
        "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c794",
        "min_kpps": 2000,
        "direction": "any"
    }
}
DELETE
/v2.0/qos/policies/{policy_id}/minimum_packet_rate_rules/{rule_id}

Delete minimum packet rate rule

Deletes a minimum packet rate rule for a QoS policy.

Normal response codes: 204

Error response codes: 400, 401, 404

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

rule_id

path

string

The ID of the QoS rule.

Response

There is no body content for the response of a successful DELETE request.

QoS packet rate limit rules

Lists, creates, deletes, shows information for, and updates QoS packet rate limit rules.

GET
/v2.0/qos/policies/{policy_id}/packet_rate_limit_rules

List packet rate limit rules for QoS policy

Lists all packet rate limit rules for a QoS policy.

The list might be empty.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

max_kpps (Optional)

query

integer

Filter the list result by the max kpps (kilo packets per second) value.

max_burst_kpps (Optional)

query

integer

Filter the list result by the max burst kpps (kilo packets per second) value.

id (Optional)

query

string

Filter the list result by the ID of the resource.

direction (Optional)

query

string

Filter the list result by the direction of the traffic to which the QoS rule is applied. Valid values are egress and ingress.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a packet rate limit rule attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • direction

  • id

  • max_kpps

  • max_burst_kpps

Response Parameters

Name

In

Type

Description

packet_rate_limit_rules

body

array

A list of packet_rate_limit_rule objects associated with the QoS policy.

max_kpps

body

integer

The max kpps (kilo packets per second) value.

max_burst_kpps

body

integer

The max burst kpps (kilo packets per second) value.

id

body

string

The ID of the QoS packet rate limit rule.

direction

body

string

The direction of the traffic to which the QoS rule is applied, as seen from the point of view of the port. Valid values are egress and ingress. Default value is egress.

tags

body

array

The list of tags on the resource.

Response Example

{
    "packet_rate_limit_rules": [
        {
            "id": "1eddf7af-0b4c-42c5-8ae1-390b32f1de08",
            "max_kpps": 10000,
            "max_burst_kpps": 10000,
            "direction": "egress"
        }
    ]
}
POST
/v2.0/qos/policies/{policy_id}/packet_rate_limit_rules

Create packet rate limit rule

Creates a packet rate limit rule for a QoS policy.

Normal response codes: 201

Error response codes: 400, 401, 404, 409

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

packet_rate_limit_rule

body

object

A packet_rate_limit_rule object.

max_kpps

body

integer

The max kpps (kilo packets per second) value.

max_burst_kpps

body

integer

The max burst kpps (kilo packets per second) value.

direction (Optional)

body

string

The direction of the traffic to which the QoS rule is applied, as seen from the point of view of the port. Valid values are egress and ingress. Default value is egress.

Request Example

{
    "packet_rate_limit_rule": {
        "max_kpps": "10000",
        "max_burst_kpps": "10000"
    }
}

Response Parameters

Name

In

Type

Description

packet_rate_limit_rule

body

object

A packet_rate_limit_rule object.

max_kpps

body

integer

The max kpps (kilo packets per second) value.

max_burst_kpps

body

integer

The max burst kpps (kilo packets per second) value.

id

body

string

The ID of the QoS packet rate limit rule.

direction

body

string

The direction of the traffic to which the QoS rule is applied, as seen from the point of view of the port. Valid values are egress and ingress. Default value is egress.

tags

body

array

The list of tags on the resource.

Response Example

{
    "packet_rate_limit_rule": {
        "id": "1eddf7af-0b4c-42c5-8ae1-390b32f1de08",
        "max_kpps": 10000,
        "max_burst_kpps": 10000,
        "direction": "egress"
    }
}
GET
/v2.0/qos/policies/{policy_id}/packet_rate_limit_rules/{rule_id}

Show packet rate limit rule details

Shows details for a packet rate limit rule for a QoS policy.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

rule_id

path

string

The ID of the QoS rule.

Response Parameters

Name

In

Type

Description

packet_rate_limit_rule

body

object

A packet_rate_limit_rule object.

max_kpps

body

integer

The max kpps (kilo packets per second) value.

max_burst_kpps

body

integer

The max burst kpps (kilo packets per second) value.

id

body

string

The ID of the QoS packet rate limit rule.

direction

body

string

The direction of the traffic to which the QoS rule is applied, as seen from the point of view of the port. Valid values are egress and ingress. Default value is egress.

tags

body

array

The list of tags on the resource.

Response Example

{
    "packet_rate_limit_rule": {
        "id": "1eddf7af-0b4c-42c5-8ae1-390b32f1de08",
        "max_kpps": 10000,
        "max_burst_kpps": 10000,
        "direction": "egress"
    }
}
PUT
/v2.0/qos/policies/{policy_id}/packet_rate_limit_rules/{rule_id}

Update packet rate limit rule

Updates a packet rate limit rule for a QoS policy.

Normal response codes: 200

Error response codes: 400, 401, 404

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

rule_id

path

string

The ID of the QoS rule.

packet_rate_limit_rule

body

object

A packet_rate_limit_rule object.

max_kpps

body

integer

The max kpps (kilo packets per second) value.

max_burst_kpps

body

integer

The max burst kpps (kilo packets per second) value.

direction (Optional)

body

string

The direction of the traffic to which the QoS rule is applied, as seen from the point of view of the port. Valid values are egress and ingress.

Request Example

{
    "packet_rate_limit_rule": {
        "max_kpps": "20000",
        "max_burst_kpps": "20000"
    }
}

Response Parameters

Name

In

Type

Description

packet_rate_limit_rule

body

object

A packet_rate_limit_rule object.

max_kpps

body

integer

The max kpps (kilo packets per second) value.

max_burst_kpps

body

integer

The max burst kpps (kilo packets per second) value.

id

body

string

The ID of the QoS packet rate limit rule.

direction

body

string

The direction of the traffic to which the QoS rule is applied, as seen from the point of view of the port. Valid values are egress and ingress.

tags

body

array

The list of tags on the resource.

Response Example

{
    "packet_rate_limit_rule": {
        "id": "1eddf7af-0b4c-42c5-8ae1-390b32f1de08",
        "max_kpps": 20000,
        "max_burst_kpps": 20000,
        "direction": "egress"
    }
}
DELETE
/v2.0/qos/policies/{policy_id}/packet_rate_limit_rules/{rule_id}

Delete packet rate limit rule

Deletes a packet rate limit rule for a QoS policy.

Normal response codes: 204

Error response codes: 400, 401, 404

Request

Name

In

Type

Description

policy_id

path

string

The ID of the QoS policy.

rule_id

path

string

The ID of the QoS rule.

Response

There is no body content for the response of a successful DELETE request.

Quality of Service rules alias API

The purpose of this API extension is to enable callers to execute the requests to delete, show and update QoS rules without specifying the corresponding policy ID. Otherwise, these requests have the exact same behavior as their counterparts described in other parts of this documentation. The requests available in this API extension are:

GET
/v2.0/qos/alias_bandwidth_limit_rules/{rule_id}

Show bandwidth limit rule details alias

Please refer to Show bandwidth limit rule details for more information on the request, response and return codes.

PUT
/v2.0/qos/alias_bandwidth_limit_rules/{rule_id}

Update bandwidth limit rule alias

Please refer to Update bandwidth limit rule for more information on the request, response and return codes.

DELETE
/v2.0/qos/alias_bandwidth_limit_rules/{rule_id}

Delete bandwidth limit rule alias

Please refer to Delete bandwidth limit rule for more information on the request, response and return codes.

GET
/v2.0/qos/alias_dscp_marking_rules/{dscp_rule_id}

Show DSCP marking rule details alias

Please refer to Show DSCP marking rule details for more information on the request, response and return codes.

PUT
/v2.0/qos/alias_dscp_marking_rules/{dscp_rule_id}

Update DSCP marking rule alias

Please refer to Update DSCP marking rule for more information on the request, response and return codes.

DELETE
/v2.0/qos/alias_dscp_marking_rules/{dscp_rule_id}

Delete DSCP marking rule alias

Please refer to Delete DSCP marking rule for more information on the request, response and return codes.

GET
/v2.0/qos/alias_minimum_bandwidth_rules/{rule_id}

Show minimum bandwidth rule details alias

Please refer to Show minimum bandwidth rule details for more information on the request, response and return codes.

PUT
/v2.0/qos/alias_minimum_bandwidth_rules/{rule_id}

Update minimum bandwidth rule alias

Please refer to Update minimum bandwidth rule for more information on the request, response and return codes.

DELETE
/v2.0/qos/alias_minimum_bandwidth_rules/{rule_id}

Delete minimum bandwidth rule alias

Please refer to Delete minimum bandwidth rule for more information on the request, response and return codes.

Quality of Service minimum packet rate rule alias API

This API extension enables callers to execute the requests to delete, show and update QoS minimum packet rate rule without specifying the corresponding policy ID.

GET
/v2.0/qos/alias_minimum_packet_rate_rules/{rule_id}

Show minimum packet rate rule details alias

Please refer to Show minimum packet rate rule details for more information on the request, response and return codes.

PUT
/v2.0/qos/alias_minimum_packet_rate_rules/{rule_id}

Update minimum packet rate rule alias

Please refer to Update minimum packet rate rule for more information on the request, response and return codes.

DELETE
/v2.0/qos/alias_minimum_packet_rate_rules/{rule_id}

Delete minimum packet rate rule alias

Please refer to Delete minimum packet rate rule for more information on the request, response and return codes.

Load Balancer as a Service 2.0 (DEPRECATED)

Neutron-lbaas is deprecated as of Queens. Load-Balancer-as-a-Service (LBaaS v2) is now provided by the Octavia project. The Octavia API v2 is backwards compatible with the neutron-lbaas implementation of the LBaaS 2.0 API.

Please see the FAQ at https://wiki.openstack.org/wiki/Neutron/LBaaS/Deprecation

Logging Resource (networking-midonet)

Logging Resources

Note

Currently this extension logging-resource is only available for networking-midonet.

Lists, shows information for, creates, updates and deletes logging resources.

GET
/v2.0/logging/logging_resources

List Logging Resources

Lists logging resources.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401, 403

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response

Name

In

Type

Description

logging_resources

body

array

A list of logging_resource objects.

id

body

string

The ID of the logging resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

firewall_logs

body

array

A list of firewall_log objects.

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

enabled

body

boolean

Indicates whether this logging resource is enabled or disabled.

Response Example

{
    "logging_resources": [
        {
            "description": "my log",
            "enabled": true,
            "firewall_logs": [],
            "id": "13b64f3c-20af-4741-b230-658ab7d5b257",
            "name": "log",
            "project_id": "8d018258316e4f22890561e8780c85bb",
            "tenant_id": "8d018258316e4f22890561e8780c85bb"
        },
        {
            "description": "my log2",
            "enabled": true,
            "firewall_logs": [],
            "id": "335c7b7d-c4a9-423a-9c24-9f4982f31e24",
            "name": "log2",
            "project_id": "8d018258316e4f22890561e8780c85bb",
            "tenant_id": "8d018258316e4f22890561e8780c85bb"
        }
    ]
}
POST
/v2.0/logging/logging_resources

Create Logging Resource

Creates a logging resource.

Normal response codes: 201

Error response codes: 400, 401, 403

Request

Name

In

Type

Description

logging_resource

body

object

A logging_resource object.

tenant_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

project_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

enabled (Optional)

body

boolean

Indicates whether this logging resource is enabled or disabled. Default is false.

Request Example

{
    "logging_resource": {
        "description": "my log",
        "enabled": true,
        "name": "log"
    }
}

Response

Name

In

Type

Description

logging_resource

body

object

A logging_resource object.

id

body

string

The ID of the logging resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

firewall_logs

body

array

A list of firewall_log objects.

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

enabled

body

boolean

Indicates whether this logging resource is enabled or disabled.

Response Example

{
    "logging_resource": {
        "description": "my log",
        "enabled": true,
        "firewall_logs": [],
        "id": "13b64f3c-20af-4741-b230-658ab7d5b257",
        "name": "log",
        "project_id": "8d018258316e4f22890561e8780c85bb",
        "tenant_id": "8d018258316e4f22890561e8780c85bb"
    }
}
GET
/v2.0/logging/logging_resources/{logging_resource_id}

Show Logging Resource Details

Shows details for a logging resource.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

logging_resource_id

path

string

The ID of the logging resource.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response

Name

In

Type

Description

logging_resource

body

object

A logging_resource object.

id

body

string

The ID of the logging resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

firewall_logs

body

array

A list of firewall_log objects.

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

enabled

body

boolean

Indicates whether this logging resource is enabled or disabled.

Response Example

{
    "logging_resource": {
        "description": "my log",
        "enabled": true,
        "firewall_logs": [
            {
                "description": "",
                "firewall_id": "682cfe44-5fcf-4c16-982e-1176493f6825",
                "fw_event": "ALL",
                "id": "1ee6fea7-c294-418e-9b97-06db48e3f3d5",
                "logging_resource_id": "13b64f3c-20af-4741-b230-658ab7d5b257",
                "project_id": "8d018258316e4f22890561e8780c85bb",
                "tenant_id": "8d018258316e4f22890561e8780c85bb"
            }
        ],
        "id": "13b64f3c-20af-4741-b230-658ab7d5b257",
        "name": "log",
        "project_id": "8d018258316e4f22890561e8780c85bb",
        "tenant_id": "8d018258316e4f22890561e8780c85bb"
    }
}
PUT
/v2.0/logging/logging_resources/{logging_resource_id}

Update Logging Resource

Updates a logging resource.

Normal response codes: 200

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

logging_resource_id

path

string

The ID of the logging resource.

logging_resource

body

object

A logging_resource object.

name (Optional)

body

string

Human-readable name of the resource.

description (Optional)

body

string

A human-readable description for the resource.

enabled (Optional)

body

boolean

Indicates whether this logging resource is enabled or disabled.

Request Example

{
    "logging_resource": {
        "description": "my log2",
        "enabled": false
    }
}

Response

Name

In

Type

Description

logging_resource

body

object

A logging_resource object.

id

body

string

The ID of the logging resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

firewall_logs

body

array

A list of firewall_log objects.

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

enabled

body

boolean

Indicates whether this logging resource is enabled or disabled.

Response Example

{
    "logging_resource": {
        "description": "my log2",
        "enabled": false,
        "firewall_logs": [
            {
                "description": "",
                "firewall_id": "682cfe44-5fcf-4c16-982e-1176493f6825",
                "fw_event": "ALL",
                "id": "1ee6fea7-c294-418e-9b97-06db48e3f3d5",
                "logging_resource_id": "335c7b7d-c4a9-423a-9c24-9f4982f31e24",
                "project_id": "8d018258316e4f22890561e8780c85bb",
                "tenant_id": "8d018258316e4f22890561e8780c85bb"
            }
        ],
        "id": "335c7b7d-c4a9-423a-9c24-9f4982f31e24",
        "name": "log2",
        "project_id": "8d018258316e4f22890561e8780c85bb",
        "tenant_id": "8d018258316e4f22890561e8780c85bb"
    }
}
DELETE
/v2.0/logging/logging_resources/{logging_resource_id}

Delete Logging Resource

Deletes a logging resource.

Normal response codes: 204

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

logging_resource_id

path

string

The ID of the logging resource.

Response

There is no body content for the response of a successful DELETE request.

Firewall Logs

Note

Currently this extension logging-resource is only available for networking-midonet.

Lists, shows information for, creates, updates and deletes firewall logs.

GET
/v2.0/logging/logging_resources/{logging_resource_id}/firewall_logs

List Firewall Logs

Lists firewall logs.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401, 403

Request

Name

In

Type

Description

logging_resource_id

path

string

The ID of the logging resource.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response

Name

In

Type

Description

firewall_logs

body

array

A list of firewall_log objects.

logging_resource_id

body

string

The ID of the logging resource.

id

body

string

The ID of the firewall log resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

description

body

string

A human-readable description for the resource.

fw_event

body

string

Type of firewall events to log. ACCEPT, DROP, or ALL.

firewall_id

body

string

The ID of the FWaaS v1 firewall.

Response Example

{
    "firewall_logs": [
        {
            "description": "my firewall log 2",
            "firewall_id": "a6564146-f8b3-49c3-add1-fb213455d5a8",
            "fw_event": "ACCEPT",
            "id": "3969b708-d600-4343-93b9-01645f8e9a8a",
            "logging_resource_id": "13b64f3c-20af-4741-b230-658ab7d5b257",
            "project_id": "8d018258316e4f22890561e8780c85bb",
            "tenant_id": "8d018258316e4f22890561e8780c85bb"
        },
        {
            "description": "my firewall log",
            "firewall_id": "a6564146-f8b3-49c3-add1-fb213455d5a8",
            "fw_event": "DROP",
            "id": "deb19331-e5d5-4a80-a37f-5e5ad407b353",
            "logging_resource_id": "13b64f3c-20af-4741-b230-658ab7d5b257",
            "project_id": "8d018258316e4f22890561e8780c85bb",
            "tenant_id": "8d018258316e4f22890561e8780c85bb"
        }
    ]
}
POST
/v2.0/logging/logging_resources/{logging_resource_id}/firewall_logs

Create Firewall Log

Creates a firewall log.

Normal response codes: 201

Error response codes: 400, 401, 403

Request

Name

In

Type

Description

logging_resource_id

path

string

The ID of the logging resource.

firewall_log

body

object

A firewall_log object.

tenant_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

project_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

fw_event (Optional)

body

string

Type of firewall events to log. ACCEPT, DROP, or ALL. Default is ALL.

firewall_id

body

string

The ID of the FWaaS v1 firewall.

Request Example

{
    "firewall_log": {
        "description": "my firewall log",
        "firewall_id": "a6564146-f8b3-49c3-add1-fb213455d5a8",
        "fw_event": "DROP"
    }
}

Response

Name

In

Type

Description

firewall_log

body

object

A firewall_log object.

logging_resource_id

body

string

The ID of the logging resource.

id

body

string

The ID of the firewall log resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

description

body

string

A human-readable description for the resource.

fw_event

body

string

Type of firewall events to log. ACCEPT, DROP, or ALL.

firewall_id

body

string

The ID of the FWaaS v1 firewall.

Response Example

{
    "firewall_log": {
        "description": "my firewall log",
        "firewall_id": "a6564146-f8b3-49c3-add1-fb213455d5a8",
        "fw_event": "DROP",
        "id": "deb19331-e5d5-4a80-a37f-5e5ad407b353",
        "logging_resource_id": "13b64f3c-20af-4741-b230-658ab7d5b257",
        "project_id": "8d018258316e4f22890561e8780c85bb",
        "tenant_id": "8d018258316e4f22890561e8780c85bb"
    }
}
GET
/v2.0/logging/logging_resources/{logging_resource_id}/firewall_logs/{firewall_log_id}

Show Firewall Log Details

Shows details for a firewall log.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

logging_resource_id

path

string

The ID of the logging resource.

firewall_log_id

path

string

The ID of the firewall log resource.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response

Name

In

Type

Description

firewall_log

body

object

A firewall_log object.

logging_resource_id

body

string

The ID of the logging resource.

id

body

string

The ID of the firewall log resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

description

body

string

A human-readable description for the resource.

fw_event

body

string

Type of firewall events to log. ACCEPT, DROP, or ALL.

firewall_id

body

string

The ID of the FWaaS v1 firewall.

Response Example

{
    "firewall_log": {
        "description": "my firewall log 3",
        "firewall_id": "a6564146-f8b3-49c3-add1-fb213455d5a8",
        "fw_event": "ALL",
        "id": "3969b708-d600-4343-93b9-01645f8e9a8a",
        "logging_resource_id": "13b64f3c-20af-4741-b230-658ab7d5b257",
        "project_id": "8d018258316e4f22890561e8780c85bb",
        "tenant_id": "8d018258316e4f22890561e8780c85bb"
    }
}
PUT
/v2.0/logging/logging_resources/{logging_resource_id}/firewall_logs/{firewall_log_id}

Update Firewall Log

Updates a firewall log.

Normal response codes: 200

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

logging_resource_id

path

string

The ID of the logging resource.

firewall_log_id

path

string

The ID of the firewall log resource.

firewall_log

body

object

A firewall_log object.

description (Optional)

body

string

A human-readable description for the resource.

fw_event (Optional)

body

string

Type of firewall events to log. ACCEPT, DROP, or ALL.

Request Example

{
    "firewall_log": {
        "description": "my firewall log 3",
        "fw_event": "ALL"
    }
}

Response

Name

In

Type

Description

firewall_log

body

object

A firewall_log object.

logging_resource_id

body

string

The ID of the logging resource.

id

body

string

The ID of the firewall log resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

description

body

string

A human-readable description for the resource.

fw_event

body

string

Type of firewall events to log. ACCEPT, DROP, or ALL.

firewall_id

body

string

The ID of the FWaaS v1 firewall.

Response Example

{
    "firewall_log": {
        "description": "my firewall log 3",
        "firewall_id": "a6564146-f8b3-49c3-add1-fb213455d5a8",
        "fw_event": "ALL",
        "id": "3969b708-d600-4343-93b9-01645f8e9a8a",
        "logging_resource_id": "13b64f3c-20af-4741-b230-658ab7d5b257",
        "project_id": "8d018258316e4f22890561e8780c85bb",
        "tenant_id": "8d018258316e4f22890561e8780c85bb"
    }
}
DELETE
/v2.0/logging/logging_resources/{logging_resource_id}/firewall_logs/{firewall_log_id}

Delete Firewall Log

Deletes a firewall log.

Normal response codes: 204

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

logging_resource_id

path

string

The ID of the logging resource.

firewall_log_id

path

string

The ID of the firewall log resource.

Response

There is no body content for the response of a successful DELETE request.

Router interface floating IP (networking-midonet)

Router Interface floating IP

Note

Currently this extension router-interface-fip is only available for networking-midonet.

This extension router-interface-fip indicates the ability to associate floating IPs to internal interfaces of a router. (Without this extension, floating IPs can be associated only to the gateway interface of a router.)

This extension does not introduce any resources or attributes.

FIP64 (networking-midonet)

FIP64

Note

Currently this extension fip64 is only available for networking-midonet.

This extension fip64 provides NAT64 functionality by allowing to associate IPv6 floating IPs to IPv4 fixed IPs. (Without this extension, floating IPs are limited to IPv4.)

This extension does not introduce any resources or attributes.

BGP/MPLS VPN Interconnection

BGP - MPLS VPN Overview

The bgpvpn extension implements the BGP VPN Interconnection API which provides the ability to associate OpenStack networks and/or routers with Multiprotocol Label Switching (MPLS) Virtual Private Networks (VPNs) via Border Gateway Protocol (BGP) peering. BGP-MPLS VPNs are commonly provided by telecommunications service providers to customers in addition to or instead of Internet connectivity for Wide Area Networking. This API enables the interconnection with these WAN VPNs using Route Targets to indicate the desired network(s).

On Route Targets

route_targets, import_targets, export_targets attributes

  • The set of RTs used for import is the union of route_targets and import_targets.

  • The set of RTs used for export is the union of route_targets and export_targets.

At least one of route_targets, import_targets or export_targets options will typically be defined, but the API will not enforce that and all lists can be empty.

For instance, in the very typical use case where the BGP VPN uses a single Route Target for both import and export, the route_targets parameter alone is enough and will contain one Route target.

On Route Distinguishers (RDs)

The route_distinguishers parameter is optional and provides an indication of the RDs that shall be used for routes announced for Neutron networks. The contract is that when a list of RDs is specified, the backend will use, for a said advertisement of a route, one of these RDs. The motivation for having a list rather than only one RD is to allow the support for multihoming a VPN prefix (typically for resiliency, load balancing or anycast). A backend may or may not support this behavior, and should report an API error in the latter case. When not specified, the backend will use automatically-assigned RDs (for instance <ip>:<number> RDs derived from the Provider Edge (PE) IP).

Valid strings for Route Distinguishers and Route Targets

Valid strings for a Route Target or a Route Distinguisher are the following:

  • <2-byte AS#>:<32bit-number>

  • <4-byte AS#>:<16bit-number>

  • <4-byte IPv4>:<16bit-number>

On VXLAN VNI

VXLAN is one option among others that could be used for BGP E-VPNs. When VXLAN is used on a hardware platform the use of a locally-assigned id may not be always possible which introduces the need to configure a globally-assigned VXLAN VNI.

The optional vni attribute is an admin-only parameter and allows the admin to enforce the use of a chosen globally-assigned VXLAN VNI for the said BGPVPN.

The default when no VNI is specified and the VXLAN encapsulation is used, is to let the backend choose the VNI in advertised routes, and use the VNI in received routes for transmitted traffic. The backend will conform to E-VPN overlay specs.

Valid range for the vni attribute is [1, 224-1].

Control of routes advertised to BGPVPNs

With the bgpvpn extension, when associations between networks or routers and BGVPNs are defined, the routes corresponding to fixed IPs of neutron ports will be advertised to BGPVPNs. For router associations, extra routes of the router (‘routes’ attribute of a router resource) may also be advertised to BGPVPNs.

To provide more flexibility, the bgpvpn-routes-control extension provides a way to:

  • advertise other routes to a BGPVPN, for instances a prefix that is reachable via a neutron port, or routes leaked from another BGPVPN; this is implemented thanks to the routes attribute of a BGPVPN port association

  • not advertise the fixed IPs of a neutron port to a BGPVPN, which can be particularly relevant when other IP prefixes are reachable via the port; this is implemented thanks to the advertise_fixed_ips attribute of a BGPVPN port association

  • explicitly control whether extra routes of a router are to be advertised to a BGPVPN; this is implemented thanks to the advertise_extra_routes attribute of a BGPVPN router association.

    Note

    This feature is under development for the Rocky release

  • optionally control the value of the LOCAL_PREF BGP attribute of advertised routes, for all routes of a BGPVPN (thanks to the local_pref attribute of a BGPVPN resource) and/or per route (thanks to the local_pref in a port association route)

BGP - MPLS VPN Caveats

Association constraints

A given BGP VPN can be associated to multiple networks and/or multiple routers.

To avoid any ambiguity on semantics in particular the context of processing associated to a router (e.g. NAT or FWaaS), if a given subnet in a network is bound to a router, this API does not allow to both associate the network to an L3 BGP VPN and the router to the same or to a distinct L3 BGP VPN.

Moreover, for BGP VPNs of type L3, there are possible cases of IP prefix overlaps that can’t be detected by the service plugin before BGP routes are received, for which the behavior is left undefined by these specifications (i.e. which of the overlapping routes is being used) and will depend on the backend. This applies for both router associations and network associations in the case where traffic is forwarded by a router and the destination IP belongs both to a prefix of a BGP VPN associated with the router or with the network originating the traffic, and to a prefix of a subnet bound to the router; in such a case whether the traffic will be delivered to the subnet or to the BGP VPN is not defined by this API.

Connectivity Impact inside OpenStack Neutron

Creating two BGP VPNs with RTs resulting in both VPNs to exchange routes, and then associating these two BGP VPNs to two networks, will result in establishing interconnectivity between these two networks, this simply being the result of applying BGP VPN Route Target semantics (i.e. without making prefixes to OpenStack networks a particular case).

This similarly applies to router associations.

BGP VPNs

A new BGPVPN resource is introduced. It contains a set of parameters for a BGP-based VPN.

A BGPVPN is created by the admin and given to a tenant who can then associate it to Networks, Routers or Ports (the latter when the bgpvpn-routes-control extension is available).

The BGP VPNs API lists, shows details for, creates, updates, and deletes BGP VPNs.

GET
/v2.0/bgpvpn/bgpvpns

List BGP VPNs

Lists BGP VPNs to which the project has access.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 400, 401, 403

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

project_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

networks (Optional)

query

array

Filter result for BGPVPNs that have a network association to at least one of the provided network_ids.

routers (Optional)

query

array

Filter result for BGPVPNs that have a router association to at least one of the provided router_ids.

ports (Optional)

query

array

Filter result for BGPVPNs that have a port association to at least one of the provided port_ids.

Response Parameters

Name

In

Type

Description

bgpvpns

body

array

A list of bgpvpn objects. Each bgpvpn object represents an MPLS network with which Neutron routers and/or networks may be associated

id

body

string

The ID of the BGP VPN.

name

body

string

The user meaningful name of the BGP VPN.

type

body

string

Selection of the type of VPN and the technology behind it. Allowed values are l2 or l3. The default is l3. l2 indicates a Layer 2 (i.e. bridged) attachment and l3 indicates a Layer 3 (i.e. routed) attachment.

route_distinguishers

body

array

List of route distinguisher strings. If this parameter is specified, one of these RDs will be used to advertise VPN routes.

route_targets

body

array

Route Targets that will be both imported and used for export.

import_targets

body

array

Additional Route Targets that will be imported.

export_targets

body

array

Additional Route Targets that will be used for export.

networks

body

array

This read-only list of network IDs reflects the associations defined by Network association API resources.

routers

body

array

This read-only list of router IDs reflects the associations defined by Router association API resources.

ports

body

array

This read-only list of port IDs reflects the associations defined by Port association API resources (only present if the bgpvpn-routes-control API extension is enabled).

local_pref

body

integer

The default BGP LOCAL_PREF of routes that will be advertised to the BGPVPN (unless overridden per-route).

vni

body

integer

The globally-assigned VXLAN vni for the BGP VPN.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

Response Example

{
  "bgpvpns": [
    {
      "export_targets": [
        "64512:1666"
      ],
      "name": "",
      "routers": [],
      "route_distinguishers": [
        "64512:1777",
        "64512:1888",
        "64512:1999"
      ],
      "tenant_id": "b7549121395844bea941bb92feb3fad9",
      "project_id": "b7549121395844bea941bb92feb3fad9",
      "import_targets": [
        "64512:1555"
      ],
      "route_targets": [
        "64512:1444"
      ],
      "type": "l3",
      "id": "0f9d472a-908f-40f5-8574-b4e8a63ccbf0",
      "networks": [],
      "local_pref": null,
      "vni": 1000
    }
  ]
}
POST
/v2.0/bgpvpn/bgpvpns

Create BGP VPNS

Creates a BGP VPN.

Normal response codes: 201

Error response codes: 400, 401

Request

Name

In

Type

Description

bgpvpn

body

object

A bgpvpn object represents an MPLS network with which Neutron routers and/or networks may be associated

name (Optional)

body

string

The user meaningful name of the BGP VPN.

route_distinguishers (Optional)

body

array

List of route distinguisher strings. If this parameter is specified, one of these RDs will be used to advertise VPN routes.

route_targets (Optional)

body

array

Route Targets that will be both imported and used for export.

import_targets (Optional)

body

array

Additional Route Targets that will be imported.

export_targets (Optional)

body

array

Additional Route Targets that will be used for export.

local_pref (Optional)

body

integer

The default BGP LOCAL_PREF of routes that will be advertised to the BGPVPN (unless overridden per-route). Defaults to null.

vni (Optional)

body

integer

The globally-assigned VXLAN vni for the BGP VPN.

tenant_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

project_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

type (Optional)

body

string

Selection of the type of VPN and the technology behind it. Allowed values are l2 or l3. The default is l3. l2 indicates a Layer 2 (i.e. bridged) attachment and l3 indicates a Layer 3 (i.e. routed) attachment.

Request Example

{
  "bgpvpn": {
    "tenant_id": "b7549121395844bea941bb92feb3fad9",
    "route_targets": "64512:1444",
    "import_targets": "64512:1555",
    "export_targets": "64512:1666",
    "route_distinguishers": ["64512:1777", "64512:1888", "64512:1999"],
    "type": "l3",
    "vni": 1000
  }
}

Response Parameters

Name

In

Type

Description

bgpvpn

body

object

A bgpvpn object represents an MPLS network with which Neutron routers and/or networks may be associated

id

body

string

The ID of the BGP VPN.

name

body

string

The user meaningful name of the BGP VPN.

type

body

string

Selection of the type of VPN and the technology behind it. Allowed values are l2 or l3. The default is l3. l2 indicates a Layer 2 (i.e. bridged) attachment and l3 indicates a Layer 3 (i.e. routed) attachment.

route_targets

body

array

Route Targets that will be both imported and used for export.

import_targets

body

array

Additional Route Targets that will be imported.

export_targets

body

array

Additional Route Targets that will be used for export.

networks

body

array

This read-only list of network IDs reflects the associations defined by Network association API resources.

routers

body

array

This read-only list of router IDs reflects the associations defined by Router association API resources.

ports

body

array

This read-only list of port IDs reflects the associations defined by Port association API resources (only present if the bgpvpn-routes-control API extension is enabled).

local_pref

body

integer

The default BGP LOCAL_PREF of routes that will be advertised to the BGPVPN (unless overridden per-route).

vni

body

integer

The globally-assigned VXLAN vni for the BGP VPN.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

Response Example

{
  "bgpvpn": {
    "export_targets": [
      "64512:1666"
    ],
    "name": "",
    "routers": [],
    "route_distinguishers": [
      "64512:1777",
      "64512:1888",
      "64512:1999"
    ],
    "tenant_id": "b7549121395844bea941bb92feb3fad9",
    "project_id": "b7549121395844bea941bb92feb3fad9",
    "import_targets": [
      "64512:1555"
    ],
    "route_targets": [
      "64512:1444"
    ],
    "type": "l3",
    "id": "0f9d472a-908f-40f5-8574-b4e8a63ccbf0",
    "networks": [],
    "local_pref": null,
    "vni": 1000
  }
}
GET
/v2.0/bgpvpn/bgpvpns/{bgpvpn_id}

Show BGP VPN details

Shows details for a BGP VPN.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 403, 404

Request

Name

In

Type

Description

bgpvpn_id

path

string

The ID of the BGP VPN.

Response Parameters

Name

In

Type

Description

bgpvpn

body

object

A bgpvpn object represents an MPLS network with which Neutron routers and/or networks may be associated

id

body

string

The ID of the BGP VPN.

name

body

string

The user meaningful name of the BGP VPN.

type

body

string

Selection of the type of VPN and the technology behind it. Allowed values are l2 or l3. The default is l3. l2 indicates a Layer 2 (i.e. bridged) attachment and l3 indicates a Layer 3 (i.e. routed) attachment.

route_distinguishers

body

array

List of route distinguisher strings. If this parameter is specified, one of these RDs will be used to advertise VPN routes.

route_targets

body

array

Route Targets that will be both imported and used for export.

import_targets

body

array

Additional Route Targets that will be imported.

export_targets

body

array

Additional Route Targets that will be used for export.

networks

body

array

This read-only list of network IDs reflects the associations defined by Network association API resources.

routers

body

array

This read-only list of router IDs reflects the associations defined by Router association API resources.

ports

body

array

This read-only list of port IDs reflects the associations defined by Port association API resources (only present if the bgpvpn-routes-control API extension is enabled).

local_pref

body

integer

The default BGP LOCAL_PREF of routes that will be advertised to the BGPVPN (unless overridden per-route).

vni

body

integer

The globally-assigned VXLAN vni for the BGP VPN.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

Response Example

{
    "bgpvpn": {
       "id": "460ac411-3dfb-45bb-8116-ed1a7233d143",
       "name": "foo",
       "route_targets": ["64512:1444"],
       "export_targets": [],
       "import_targets": [],
       "type": "l3",
       "tenant_id": "f94ea398564d49dfb0d542f086c68ce7",
       "project_id": "f94ea398564d49dfb0d542f086c68ce7",
       "routers": [],
       "route_distinguishers": [],
       "networks": [
         "a4f2b8df-cb42-4893-a333-d0b5c36ade17"
       ],
       "local_pref": null,
       "vni": 1000
    }
}
PUT
/v2.0/bgpvpn/bgpvpns/{bgpvpn_id}

Update a BGP VPN

Updates a BGP VPN.

Normal response codes: 201

Error response codes: 400, 401, 403, 404

Request

A non-admin user can only update the name parameter. All other updates require admin privileges.

Name

In

Type

Description

bgpvpn_id

path

string

The ID of the BGP VPN.

bgpvpn

body

object

A bgpvpn object represents an MPLS network with which Neutron routers and/or networks may be associated

name (Optional)

body

string

The user meaningful name of the BGP VPN.

route_distinguishers (Optional)

body

array

List of route distinguisher strings. If this parameter is specified, one of these RDs will be used to advertise VPN routes.

route_targets (Optional)

body

array

Route Targets that will be both imported and used for export.

import_targets (Optional)

body

array

Additional Route Targets that will be imported.

export_targets (Optional)

body

array

Additional Route Targets that will be used for export.

local_pref (Optional)

body

integer

The default BGP LOCAL_PREF of routes that will be advertised to the BGPVPN (unless overridden per-route). Defaults to null.

Request Example

{
    "bgpvpn": {
       "name": "foo",
       "route_targets": ["64512:1444"],
       "export_targets": [],
       "import_targets": []
    }
}

Response Parameters

Name

In

Type

Description

bgpvpn

body

object

A bgpvpn object represents an MPLS network with which Neutron routers and/or networks may be associated

id

body

string

The ID of the BGP VPN.

name

body

string

The user meaningful name of the BGP VPN.

type

body

string

Selection of the type of VPN and the technology behind it. Allowed values are l2 or l3. The default is l3. l2 indicates a Layer 2 (i.e. bridged) attachment and l3 indicates a Layer 3 (i.e. routed) attachment.

route_distinguishers

body

array

List of route distinguisher strings. If this parameter is specified, one of these RDs will be used to advertise VPN routes.

route_targets

body

array

Route Targets that will be both imported and used for export.

import_targets

body

array

Additional Route Targets that will be imported.

export_targets

body

array

Additional Route Targets that will be used for export.

networks

body

array

This read-only list of network IDs reflects the associations defined by Network association API resources.

routers

body

array

This read-only list of router IDs reflects the associations defined by Router association API resources.

ports

body

array

This read-only list of port IDs reflects the associations defined by Port association API resources (only present if the bgpvpn-routes-control API extension is enabled).

local_pref

body

integer

The default BGP LOCAL_PREF of routes that will be advertised to the BGPVPN (unless overridden per-route).

vni

body

integer

The globally-assigned VXLAN vni for the BGP VPN.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

Response Example

{
  "bgpvpn": {
    "export_targets": [],
    "name": "",
    "routers": [],
    "route_distinguishers": [
      "12345:1234"
    ],
    "tenant_id": "b7549121395844bea941bb92feb3fad9",
    "import_targets": [],
    "route_targets": ["64512:1444"],
    "type": "l3",
    "id": "4d627abf-06dd-45ab-920b-8e61422bb984",
    "networks": [],
    "local_pref": null,
    "vni": 1000
  }
}
DELETE
/v2.0/bgpvpn/bgpvpns/{bgpvpn_id}

Delete BGP VPN

Deletes a BGP VPN and its network and/or router associations.

Normal response codes: 204

Error response codes: 401, 403, 404

Request

Name

In

Type

Description

bgpvpn_id

path

string

The ID of the BGP VPN.

Response

There is no body content for the response of a successful DELETE request.

Network Associations

Associating a BGPVPN to a Network can be done for both BGPVPN of type L2 and of type L3. For type L3, the semantic is that all Subnets bound to the Network will be interconnected with the BGP VPN (and thus between themselves).

A given Network can be associated with multiple BGPVPNs.

Associating or disassociating a BGPVPN to a Network is done by manipulating a Network association API resource as a sub-resource of the BGPVPN resource:

GET
/v2.0/bgpvpn/bgpvpns/{bgpvpn_id}/network_associations

List Network Associations

Lists network associations for a given BGP VPN.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

bgpvpn_id

path

string

The ID of the BGP VPN.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

network_associations

body

object

A list of network_association objects which represent bindings of MPLS networks to Neutron networks.

id

body

string

The ID of an association between a network and a BGP VPN.

network_id

body

string

The ID of a Neutron network with which to associate the BGP VPN.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

Response Example

{
  "network_associations": [
    {
      "network_id": "8c5d88dc-60ac-4b02-a65a-36b65888ddcd",
      "tenant_id": "b7549121395844bea941bb92feb3fad9",
      "project_id": "b7549121395844bea941bb92feb3fad9",
      "id": "96227c78-6a0c-4d9d-b441-c4b8f6fb6c4a"
    },
    {
      "network_id": "a4f2b8df-cb42-4893-a333-d0b5c36ade17",
      "tenant_id": "b7549121395844bea941bb92feb3fad9",
      "project_id": "b7549121395844bea941bb92feb3fad9",
      "id": "1b09fd12-c769-4be7-9c26-dececa474acf"
    }
  ]
}
POST
/v2.0/bgpvpn/bgpvpns/{bgpvpn_id}/network_associations

Create Network Association

Creates a network association for a given BGP VPN

Normal response codes: 201

Error response codes: 400, 401, 404

Request

Name

In

Type

Description

bgpvpn_id

path

string

The ID of the BGP VPN.

network_association

body

object

A network_association object represents the binding of a BGP VPN to a Neutron network.

network_id

body

string

The ID of a Neutron network with which to associate the BGP VPN.

Request Example

{
  "network_association": {
    "network_id": "8c5d88dc-60ac-4b02-a65a-36b65888ddcd"
  }
}

Response Parameters

Name

In

Type

Description

network_association

body

object

A network_association object represents the binding of a BGP VPN to a Neutron network.

id

body

string

The ID of an association between a network and a BGP VPN.

network_id

body

string

The ID of a Neutron network with which to associate the BGP VPN.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

Response Example

{
  "network_association": {
    "network_id": "8c5d88dc-60ac-4b02-a65a-36b65888ddcd",
    "tenant_id": "b7549121395844bea941bb92feb3fad9",
    "project_id": "b7549121395844bea941bb92feb3fad9",
    "id": "73238ca1-e05d-4c7a-b4d4-70407b4b8730"
  }
}
GET
/v2.0/bgpvpn/bgpvpns/{bgpvpn_id}/network_associations/{network_association_id}

Show Network Association details

Shows details for a network association.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 403, 404

Request

Name

In

Type

Description

bgpvpn_id

path

string

The ID of the BGP VPN.

network_association_id

path

string

The ID of an association between a network and a BGP VPN.

Response Parameters

Name

In

Type

Description

network_association

body

object

A network_association object represents the binding of a BGP VPN to a Neutron network.

id

body

string

The ID of an association between a network and a BGP VPN.

network_id

body

string

The ID of a Neutron network with which to associate the BGP VPN.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

Response Example

{
    "network_association":
       {
          "id": "1b09fd12-c769-4be7-9c26-dececa474acf",
          "network_id": "a4f2b8df-cb42-4893-a333-d0b5c36ade17",
          "tenant_id": "b7549121395844bea941bb92feb3fad9",
          "project_id": "b7549121395844bea941bb92feb3fad9"
       }
}
DELETE
/v2.0/bgpvpn/bgpvpns/{bgpvpn_id}/network_associations/{network_association_id}

Delete Network Association

Deletes a network association.

Normal response codes: 204

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

bgpvpn_id

path

string

The ID of the BGP VPN.

network_association_id

path

string

The ID of an association between a network and a BGP VPN.

Response

There is no body content for the response of a successful DELETE request.

Router Associations

Associating a BGPVPN to a Router can be done only for BGPVPN of type L3. The semantic is that all Subnets bound to the Router will be interconnected with the BGPVPN.

A said Router can be associated with multiple BGPVPNs.

Associating or disassociating a BGPVPN to a Router is done by manipulating a Router association API resource as a sub-resource of the BGPVPN resource:

Advertising router extra routes to a BGPVPN

The bgpvpn-routes-control API extension allows to control the re-advertisement of a router extra routes in a BGPVPN (“extra routes” are routes defined in the routes attribute of a router when the extraroute extension is available).

The advertise_extra_routes attribute can in this case be set on a router_association:

  • true: the extra routes defined in the routes attribute of the router will be advertised to the BGPVPN (default value)

  • false: the extra routes defined in the routes attribute of the router will not be advertised to the BGPVPN

GET
/v2.0/bgpvpn/bgpvpns/{bgpvpn_id}/router_associations

List Router Associations

Lists router associations for a given BGP VPN.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

bgpvpn_id

path

string

The ID of the BGP VPN.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

router_associations

body

object

A list of router_association objects which represent bindings of MPLS networks to Neutron routers.

id

body

string

The ID of an association between a router and a BGP VPN.

router_id

body

string

The ID of a Neutron router with which to associate the BGP VPN.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

Response Example

{
  "router_associations": [
    {
      "router_id": "61222227-49eb-4dcc-b2d6-66bbfb2fdd7a",
      "tenant_id": "b7549121395844bea941bb92feb3fad9",
      "project_id": "b7549121395844bea941bb92feb3fad9",
      "id": "95277be7-a231-4e96-9625-8f9fe41de9d6",
      "advertise_extra_routes": true
    }
  ]
}
POST
/v2.0/bgpvpn/bgpvpns/{bgpvpn_id}/router_associations

Create Router Association

Creates a router association for a given BGP VPN

Normal response codes: 201

Error response codes: 400, 401, 404

Request

Name

In

Type

Description

bgpvpn_id

path

string

The ID of the BGP VPN.

router_association

body

object

A router_association object represents the binding of a BGP VPN to a Neutron router.

router_id

body

string

The ID of a Neutron router with which to associate the BGP VPN.

Request Example

{
  "router_association": {
    "router_id": "b58a6241-6e49-4b11-87c6-8e0606dde796"
  }
}

Response Parameters

Name

In

Type

Description

router_association

body

object

A router_association object represents the binding of a BGP VPN to a Neutron router.

id

body

string

The ID of an association between a router and a BGP VPN.

router_id

body

string

The ID of a Neutron router with which to associate the BGP VPN.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

Response Example

{
  "router_association": {
    "router_id": "46a1a80b-7c42-4c45-88fd-b531e636969f",
    "tenant_id": "b7549121395844bea941bb92feb3fad9",
    "project_id": "b7549121395844bea941bb92feb3fad9",
    "id": "c63149a0-a0b3-4ca7-aba4-9aaa1b39d7f3",
    "advertise_extra_routes": true
  }
}
GET
/v2.0/bgpvpn/bgpvpns/{bgpvpn_id}/router_associations/{router_association_id}

Show Router Association details

Shows details for a router association.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 403, 404

Request

Name

In

Type

Description

bgpvpn_id

path

string

The ID of the BGP VPN.

router_association_id

path

string

The ID of an association between a router and a BGP VPN.

Response Parameters

Name

In

Type

Description

router_association

body

object

A router_association object represents the binding of a BGP VPN to a Neutron router.

id

body

string

The ID of an association between a router and a BGP VPN.

router_id

body

string

The ID of a Neutron router with which to associate the BGP VPN.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

Response Example

{
    "router_association": {
        "id": "c63149a0-a0b3-4ca7-aba4-9aaa1b39d7f3",
        "router_id": "46a1a80b-7c42-4c45-88fd-b531e636969f",
        "tenant_id": "b7549121395844bea941bb92feb3fad9",
        "project_id": "b7549121395844bea941bb92feb3fad9",
        "advertise_extra_routes": true
    }
}
PUT
/v2.0/bgpvpn/bgpvpns/{bgpvpn_id}/router_associations/{router_association_id}

Update a Router Association (‘bgpvpn-routes-control’ extension)

Note

This operation is only available when the bgpvpn-routes-control API extension is enabled.

Updates a router association.

Normal response codes: 201

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

bgpvpn_id

path

string

The ID of the BGP VPN.

router_association_id

path

string

The ID of an association between a router and a BGP VPN.

router_association

body

object

A router_association object represents the binding of a BGP VPN to a Neutron router.

advertise_extra_routes (Optional)

body

boolean

Boolean flag controlling whether or not the routes specified in the routes attribute of the router will be advertised to the BGPVPN (default: true).

Request Example

{
    "router_association": {
        "router_id": "46a1a80b-7c42-4c45-88fd-b531e636969f",
        "advertise_extra_routes": false
    }
}

Response Parameters

Name

In

Type

Description

router_association

body

object

A router_association object represents the binding of a BGP VPN to a Neutron router.

id

body

string

The ID of an association between a router and a BGP VPN.

router_id

body

string

The ID of a Neutron router with which to associate the BGP VPN.

project_id

body

string

The ID of the project.

advertise_extra_routes

body

boolean

Boolean flag controlling whether or not the routes specified in the routes attribute of the router will be advertised to the BGPVPN.

Response Example

{
    "router_association": {
        "id": "c63149a0-a0b3-4ca7-aba4-9aaa1b39d7f3",
        "project_id": "b7549121395844bea941bb92feb3fad9",
        "router_id": "46a1a80b-7c42-4c45-88fd-b531e636969f",
        "advertise_extra_routes": false
    }
}
DELETE
/v2.0/bgpvpn/bgpvpns/{bgpvpn_id}/router_associations/{router_association_id}

Delete Router Association

Deletes a router association.

Normal response codes: 204

Error response codes: 401, 403, 404

Request

Name

In

Type

Description

bgpvpn_id

path

string

The ID of the BGP VPN.

router_association_id

path

string

The ID of an association between a router and a BGP VPN.

Response

There is no body content for the response of a successful DELETE request.

Port Associations

Port associations are available if the bgpvpn-routes-control extension is available.

Associating or disassociating a BGPVPN to a Port is done by manipulating a Port association API resource as a sub-resource of the BGPVPN resource.

The semantic behind this API call is a form of policy-based routing: the traffic from the given Port will be processed according to dataplane lookups specific to this Port. This means, in particular that Ports belonging to a given neutron network will possibly see a different L2 or L3 connectivity if they have different BGPVPN associations.

When, a port association is defined for a given port, and at the same time, a network association is defined for the port’s network, both associations are considered simultaneously active and the connectivity will be established between the port and the BGPVPNs in both associations. This is true also in the case where multiple associations are made, and for a router associations of a router connected to the port’s network.

Port routes

Additionally to providing Port-level granularity in the definition of BGPVPN connectivity, port associations also provide a way to control the advertisement of routes other than only the fixed IPs of neutron ports.

So-called static routes are defined as follows: to indicate that prefix 20.1.0.0/16 is reachable via port A and should be advertised accordingly in BGPVPN X, a port association is defined between port A and BGPVPN X, with the routes attribute set to [ {'type': 'prefix', 'prefix': '20.1.0.0/16'} ].

Route leaking of the routes of a given BGPVPN into another BGPVPN belonging to the same tenant, is supported similarily: to indicate that all the prefixes advertised to BGPVPN Y are reachable via port A (i.e. the routes tagged with at least an RT belonging to route_targets or import_targets of BGPVPN Y), and that they should be leaked into BGPVPN X, a port association is defined between port A and BGPVPN X, with the routes attribute set to [ {'type': 'bgpvpn', 'bgpvpn_id': <uuid of BGPVPN Y>} ].

Control of BGP LOCAL_PREF attribute

The BGP LOCAL_PREF for a specific route can be controlled to take a different value than the one defined in the BGPVPN local_pref attribute, by adding a 'local_pref': VALUE in a route in the routes attribute (see example in port association Update request).

GET
/v2.0/bgpvpn/bgpvpns/{bgpvpn_id}/port_associations

List Port Associations

Lists port associations for a given BGP VPN.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401, 403, 404

Request

Name

In

Type

Description

bgpvpn_id

path

string

The ID of the BGP VPN.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

port_associations

body

array

A list of port_association objects which represent bindings of MPLS networks to Neutron ports.

id

body

string

The ID of an association between a port and a BGP VPN.

port_id

body

string

The ID of a Neutron port with which to associate the BGP VPN.

project_id

body

string

The ID of the project.

routes

body

array

List of routes, each route being a dict with at least a type key, which can be prefix or bgpvpn.

For the prefix type, the IP prefix (v4 or v6) to advertise is specified in the prefix key.

For the bgpvpn type, the bgpvpn_id key specifies the BGPVPN from which routes will be readvertised with the association port as the nexthop (any route carrying an RT among route_targets or import_targets of this BGPVPN, will be re-announced toward the RTs of the associated BGPVPN (export_targets + route_targets), with their next-hop/label pointing to this port).

For both types, the local_pref key can be used to control the value of the BGP LOCAL_PREF of the routes that will be advertised.

advertise_fixed_ips

body

boolean

Boolean flag controlling whether or not the fixed IPs of a port will be advertised to the BGPVPN.

Response Example

{
    "port_associations": [
        {
            "id": "95277be7-a231-4e96-9625-8f9fe41de9d6",
            "port_id": "61222227-49eb-4dcc-b2d6-66bbfb2fdd7a",
            "project_id": "b7549121395844bea941bb92feb3fad9",
            "routes": [
                {
                    "type": "prefix",
                    "prefix": "20.1.0.0/16"
                }
            ],
            "advertise_fixed_ips": true
        }
    ]
}
POST
/v2.0/bgpvpn/bgpvpns/{bgpvpn_id}/port_associations

Create Port Association

Creates a port association for a given BGP VPN

Normal response codes: 201

Error response codes: 400, 401, 404

Request

Name

In

Type

Description

bgpvpn_id

path

string

The ID of the BGP VPN.

port_association

body

object

A port_association object represents the binding of a BGP VPN to a Neutron port.

port_id

body

string

The ID of a Neutron port with which to associate the BGP VPN.

routes (Optional)

body

array

List of routes, each route being a dict with at least a type key, which can be prefix or bgpvpn.

For the prefix type, the IP prefix (v4 or v6) to advertise is specified in the prefix key.

For the bgpvpn type, the bgpvpn_id key specifies the BGPVPN from which routes will be readvertised with the association port as the nexthop (any route carrying an RT among route_targets or import_targets of this BGPVPN, will be re-announced toward the RTs of the associated BGPVPN (export_targets + route_targets), with their next-hop/label pointing to this port).

For both types, the local_pref key can be used to control the value of the BGP LOCAL_PREF of the routes that will be advertised.

advertise_fixed_ips (Optional)

body

boolean

Boolean flag controlling whether or not the fixed IPs of a port will be advertised to the BGPVPN (default: true).

Request Example

{
    "port_association": {
        "port_id": "b58a6241-6e49-4b11-87c6-8e0606dde796",
        "routes": [
            {
                "type": "prefix",
                "prefix": "20.1.0.0/16"
            }
        ]
    }
}

Response Parameters

Name

In

Type

Description

port_association

body

object

A port_association object represents the binding of a BGP VPN to a Neutron port.

id

body

string

The ID of an association between a port and a BGP VPN.

port_id

body

string

The ID of a Neutron port with which to associate the BGP VPN.

project_id

body

string

The ID of the project.

routes

body

array

List of routes, each route being a dict with at least a type key, which can be prefix or bgpvpn.

For the prefix type, the IP prefix (v4 or v6) to advertise is specified in the prefix key.

For the bgpvpn type, the bgpvpn_id key specifies the BGPVPN from which routes will be readvertised with the association port as the nexthop (any route carrying an RT among route_targets or import_targets of this BGPVPN, will be re-announced toward the RTs of the associated BGPVPN (export_targets + route_targets), with their next-hop/label pointing to this port).

For both types, the local_pref key can be used to control the value of the BGP LOCAL_PREF of the routes that will be advertised.

advertise_fixed_ips

body

boolean

Boolean flag controlling whether or not the fixed IPs of a port will be advertised to the BGPVPN.

Response Example

{
    "port_association": {
        "id": "c63149a0-a0b3-4ca7-aba4-9aaa1b39d7f3",
        "port_id": "46a1a80b-7c42-4c45-88fd-b531e636969f",
        "project_id": "b7549121395844bea941bb92feb3fad9",
        "routes": [
            {
                "type": "prefix",
                "prefix": "20.1.0.0/16"
            }
        ],
        "advertise_fixed_ips": true
    }
}
GET
/v2.0/bgpvpn/bgpvpns/{bgpvpn_id}/port_associations/{port_association_id}

Show Port Association details

Shows details for a port association.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 403, 404

Request

Name

In

Type

Description

bgpvpn_id

path

string

The ID of the BGP VPN.

port_association_id

path

string

The ID of an association between a port and a BGP VPN.

Response Parameters

Name

In

Type

Description

port_association

body

object

A port_association object represents the binding of a BGP VPN to a Neutron port.

id

body

string

The ID of an association between a port and a BGP VPN.

port_id

body

string

The ID of a Neutron port with which to associate the BGP VPN.

project_id

body

string

The ID of the project.

routes

body

array

List of routes, each route being a dict with at least a type key, which can be prefix or bgpvpn.

For the prefix type, the IP prefix (v4 or v6) to advertise is specified in the prefix key.

For the bgpvpn type, the bgpvpn_id key specifies the BGPVPN from which routes will be readvertised with the association port as the nexthop (any route carrying an RT among route_targets or import_targets of this BGPVPN, will be re-announced toward the RTs of the associated BGPVPN (export_targets + route_targets), with their next-hop/label pointing to this port).

For both types, the local_pref key can be used to control the value of the BGP LOCAL_PREF of the routes that will be advertised.

advertise_fixed_ips

body

boolean

Boolean flag controlling whether or not the fixed IPs of a port will be advertised to the BGPVPN.

Response Example

{
    "port_association": {
        "id": "c63149a0-a0b3-4ca7-aba4-9aaa1b39d7f3",
        "port_id": "46a1a80b-7c42-4c45-88fd-b531e636969f",
        "project_id": "b7549121395844bea941bb92feb3fad9",
        "routes": [
            {
                "type": "prefix",
                "prefix": "20.1.0.0/16"
            }
        ],
        "advertise_fixed_ips": true
    }
}
PUT
/v2.0/bgpvpn/bgpvpns/{bgpvpn_id}/port_associations/{port_association_id}

Update a Port Association

Updates a port Association.

Normal response codes: 201

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

bgpvpn_id

path

string

The ID of the BGP VPN.

port_association_id

path

string

The ID of an association between a port and a BGP VPN.

port_association

body

object

A port_association object represents the binding of a BGP VPN to a Neutron port.

routes (Optional)

body

array

List of routes, each route being a dict with at least a type key, which can be prefix or bgpvpn.

For the prefix type, the IP prefix (v4 or v6) to advertise is specified in the prefix key.

For the bgpvpn type, the bgpvpn_id key specifies the BGPVPN from which routes will be readvertised with the association port as the nexthop (any route carrying an RT among route_targets or import_targets of this BGPVPN, will be re-announced toward the RTs of the associated BGPVPN (export_targets + route_targets), with their next-hop/label pointing to this port).

For both types, the local_pref key can be used to control the value of the BGP LOCAL_PREF of the routes that will be advertised.

advertise_fixed_ips (Optional)

body

boolean

Boolean flag controlling whether or not the fixed IPs of a port will be advertised to the BGPVPN (default: true).

Request Example

{
    "port_association": {
        "port_id": "46a1a80b-7c42-4c45-88fd-b531e636969f",
        "routes": [
            {
                "type": "bgpvpn",
                "bgpvpn_id": "180630e3-9eae-4ba7-9939-d5f47966e1f0",
                "local_pref": 111
            }
        ],
        "advertise_fixed_ips": false
    }
}

Response Parameters

Name

In

Type

Description

port_association

body

object

A port_association object represents the binding of a BGP VPN to a Neutron port.

id

body

string

The ID of an association between a port and a BGP VPN.

port_id

body

string

The ID of a Neutron port with which to associate the BGP VPN.

project_id

body

string

The ID of the project.

routes

body

array

List of routes, each route being a dict with at least a type key, which can be prefix or bgpvpn.

For the prefix type, the IP prefix (v4 or v6) to advertise is specified in the prefix key.

For the bgpvpn type, the bgpvpn_id key specifies the BGPVPN from which routes will be readvertised with the association port as the nexthop (any route carrying an RT among route_targets or import_targets of this BGPVPN, will be re-announced toward the RTs of the associated BGPVPN (export_targets + route_targets), with their next-hop/label pointing to this port).

For both types, the local_pref key can be used to control the value of the BGP LOCAL_PREF of the routes that will be advertised.

advertise_fixed_ips

body

boolean

Boolean flag controlling whether or not the fixed IPs of a port will be advertised to the BGPVPN.

Response Example

{
    "port_association": {
        "id": "c63149a0-a0b3-4ca7-aba4-9aaa1b39d7f3",
        "port_id": "46a1a80b-7c42-4c45-88fd-b531e636969f",
        "project_id": "b7549121395844bea941bb92feb3fad9",
        "routes": [
            {
                "type": "bgpvpn",
                "bgpvpn_id": "180630e3-9eae-4ba7-9939-d5f47966e1f0",
                "local_pref": 111
            }
        ],
        "advertise_fixed_ips": false
    }
}
DELETE
/v2.0/bgpvpn/bgpvpns/{bgpvpn_id}/port_associations/{port_association_id}

Delete Port Association

Deletes a port association.

Normal response codes: 204

Error response codes: 401, 403, 404

Request

Name

In

Type

Description

bgpvpn_id

path

string

The ID of the BGP VPN.

port_association_id

path

string

The ID of an association between a port and a BGP VPN.

Response

There is no body content for the response of a successful DELETE request.

BGP Dynamic Routing

BGP Speaker

BGP Speaker acts as a route server using BGP routing protocol. It advertises routes to the BGP peers which are added to the BGP Speaker. Currently, BGP Speaker only advertises routes for a network to which it is associated.

A BGP Speaker requires association with a “gateway” network to determine eligible routes. In Neutron, a “gateway” network connects Neutron routers to the upstream routers. An external network is best for being used as a gateway network.

The association builds a list of all virtual routers with gateways on provider and self-service networks within the same address scope.

GET
/v2.0/bgp-speakers

List BGP Speakers

Issue a GET request to /v2.0/bgp-speakers to retrieve this list of available BGP Speakers.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 400, 401, 403

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

bgp_speakers

body

array

A list of bgp_speaker objects. Each bgp_speaker object acts as a route server using BGP routing protocol.

id

body

string

The ID of the BGP Speaker.

name

body

string

The user meaningful name of the BGP Speaker.

ip_version

body

string

The IP version (4 or 6) of the BGP Speaker.

advertise_floating_ip_host_routes

body

string

Whether to enable or disable the advertisement of floating ip host routes by the BGP Speaker. True by default.

advertise_tenant_networks

body

string

Whether to enable or disable the advertisement of tenant network routes by the BGP Speaker. True by default.

local_as

body

string

The local Autonomous System number of the BGP Speaker.

networks

body

string

The ID of the network to which the BGP Speaker is associated.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

Response Example

{
  "bgp_speakers":[
     {
        "peers":[
        ],
        "name":"bgp-speaker-1",
        "tenant_id":"34a6e17a48cf414ebc890367bf42266b",
        "local_as":1001,
        "advertise_tenant_networks":true,
        "networks":[
        ],
        "ip_version":4,
        "advertise_floating_ip_host_routes":true,
        "id":"5e08db80-db77-4b5c-a56d-dbca0b284f2c"
     },
     {
        "peers":[
        ],
        "name":"bgp-speaker",
        "tenant_id":"34a6e17a48cf414ebc890367bf42266b",
        "local_as":1000,
        "advertise_tenant_networks":true,
        "networks":[
        ],
        "ip_version":4,
        "advertise_floating_ip_host_routes":true,
        "id":"b759b2a1-27f4-4a6b-bb61-f2c9a22c9902"
     }
  ]
}
GET
/v2.0/bgp-speakers/{bgp-speaker-id}

Show BGP Speaker details

Issue a GET request to /v2.0/bgp-speakers/<bgp-speaker-id> to retrieve the detail about a specific BGP Speaker.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

bgp-speaker-id

path

string

The ID of the BGP Speaker.

Response Parameters

Name

In

Type

Description

id

body

string

The ID of the BGP Speaker.

name

body

string

The user meaningful name of the BGP Speaker.

ip_version

body

string

The IP version (4 or 6) of the BGP Speaker.

advertise_floating_ip_host_routes

body

string

Whether to enable or disable the advertisement of floating ip host routes by the BGP Speaker. True by default.

advertise_tenant_networks

body

string

Whether to enable or disable the advertisement of tenant network routes by the BGP Speaker. True by default.

local_as

body

string

The local Autonomous System number of the BGP Speaker.

networks

body

string

The ID of the network to which the BGP Speaker is associated.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

Response Example

{
   "bgp_speaker": {
      "peers": [
      ],
      "name": "bgp-speaker-1",
      "tenant_id": "34a6e17a48cf414ebc890367bf42266b",
      "local_as": 1001,
      "advertise_tenant_networks": true,
      "networks": [
      ],
      "ip_version": 4,
      "advertise_floating_ip_host_routes": true,
      "id": "5e08db80-db77-4b5c-a56d-dbca0b284f2c"
   }
}
POST
/v2.0/bgp-speakers

Create BGP Speaker

Issue a POST request to /v2.0/bgp-speakers with following JSON-encoded data to create a BGP Speaker.

Normal response codes: 201

Error response codes: 401, 403, 404, 409

Request

Name

In

Type

Description

name

body

string

The user meaningful name of the BGP Speaker.

ip_version

body

string

The IP version (4 or 6) of the BGP Speaker.

advertise_floating_ip_host_routes

body

string

Whether to enable or disable the advertisement of floating ip host routes by the BGP Speaker. True by default.

advertise_tenant_networks

body

string

Whether to enable or disable the advertisement of tenant network routes by the BGP Speaker. True by default.

local_as

body

string

The local Autonomous System number of the BGP Speaker.

networks

body

string

The ID of the network to which the BGP Speaker is associated.

Request Example

{
   "bgp_speaker":{
      "ip_version":4,
      "local_as":"1000",
      "name":"bgp-speaker"
   }
}

Response Parameters

Name

In

Type

Description

id

body

string

The ID of the BGP Speaker.

name

body

string

The user meaningful name of the BGP Speaker.

ip_version

body

string

The IP version (4 or 6) of the BGP Speaker.

advertise_floating_ip_host_routes

body

string

Whether to enable or disable the advertisement of floating ip host routes by the BGP Speaker. True by default.

advertise_tenant_networks

body

string

Whether to enable or disable the advertisement of tenant network routes by the BGP Speaker. True by default.

local_as

body

string

The local Autonomous System number of the BGP Speaker.

networks

body

string

The ID of the network to which the BGP Speaker is associated.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

Response Example

{
   "bgp_speaker":{
      "peers":[
      ],
      "name":"bgp-speaker",
      "tenant_id":"34a6e17a48cf414ebc890367bf42266b",
      "local_as":1000,
      "advertise_tenant_networks":true,
      "networks":[
      ],
      "ip_version":4,
      "advertise_floating_ip_host_routes":true,
      "id":"5e08db80-db77-4b5c-a56d-dbca0b284f2c"
   }
}
PUT
/v2.0/bgp-speakers/{bgp-speaker-id}

Update a BGP Speaker

Issue PUT request to /v2.0/bgp-speakers/<bgp-speaker-id> to update a specific BGP Speaker. Following attributes can be updated.

Normal response codes: 200

Error response codes: 400, 401, 404, 41

Request

Name

In

Type

Description

bgp-speakeriid

path

string

The ID of the BGP Speaker.

name

body

string

The user meaningful name of the BGP Speaker.

advertise_floating_ip_host_routes

body

string

Whether to enable or disable the advertisement of floating ip host routes by the BGP Speaker. True by default.

advertise_tenant_networks

body

string

Whether to enable or disable the advertisement of tenant network routes by the BGP Speaker. True by default.

Request Example

{
   "bgp_speaker":{
      "advertise_floating_ip_host_routes": "true",
      "advertise_tenant_networks": "false",
      "name":"bgp-speaker_2"
   }
}
DELETE
/v2.0/bgp-speakers/{bgp-speaker-id}

Delete a BGP Speaker

Delete a specific BGP Speaker.

Normal response codes: 204

Error response codes: 400, 401, 404, 412

Request

Name

In

Type

Description

bgp-speakeri-id

path

string

The ID of the BGP Speaker.

Response

There is no body content for the response of a successful DELETE request.

PUT
/v2.0/bgp-speakers/{bgp-speaker-id}/add_bgp_peer

Add BGP Peer to a BGP Speaker

Bind the BGP peer to the specified BGP Speaker.

Normal response codes: 200

Request

Name

In

Type

Description

bgp-speaker-id

path

string

The ID of the BGP Speaker.

bgp_peer_id

body

string

The id of the peer.

Request Example

{
   "bgp_peer_id":"a7193581-a31c-4ea5-8218-b3052758461f"
}

Response Parameters

Name

In

Type

Description

bgp_peer_id

body

string

The id of the peer.

Response Example

{
   "bgp_peer_id":"a7193581-a31c-4ea5-8218-b3052758461f"
}
PUT
/v2.0/bgp-speakers/{bgp-speaker-id}/remove_bgp_peer

Remove BGP Peer from a BGP Speaker

Unbind the BGP peer from a BGP Speaker.

Normal response codes: 200

Request

Name

In

Type

Description

bgp-speaker-id

path

string

The ID of the BGP Speaker.

bgp_peer_id

body

string

The id of the peer.

Request Example

{
   "bgp_peer_id":"a7193581-a31c-4ea5-8218-b3052758461f"
}

Response

There is no body content for the response of a successful DELETE request.

PUT
/v2.0/bgp-speakers/{bgp-speaker-id}/add_gateway_network

Add Network to a BGP Speaker

Add a network to the specified BGP speaker.

Normal response codes: 200

Request

Name

In

Type

Description

bgp-speaker-id

path

string

The ID of the BGP Speaker.

network_id

body

string

The ID of the attached network.

Request Example

{
   "network_id":"f2269b61-6755-4174-8f64-5e318617b204"
}

Response Parameters

Name

In

Type

Description

bgp_peer_id

body

string

The id of the peer.

network_id

body

string

The ID of the attached network.

Response Example

{
   "network_id":"f2269b61-6755-4174-8f64-5e318617b204"
}
PUT
/v2.0/bgp-speakers/{bgp-speaker-id}/remove_gateway_network

Delete Network from a BGP Speaker

Remove a network from the specified BGP speaker.

Normal response codes: 200

Request

Name

In

Type

Description

bgp-speaker-id

path

string

The ID of the BGP Speaker.

network_id

body

string

The ID of the attached network.

Request Example

{
   "network_id":"f2269b61-6755-4174-8f64-5e318617b204"
}

Response

There is no body content for the response of a successful DELETE request.

GET
/v2.0/bgp-speakers/{bgp-speaker-id}/get_advertised_routes

List routes advertised by a BGP Speaker

List all routes advertised by the specified BGP Speaker.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Response Parameters

Name

In

Type

Description

advertised_routes

body

array

A list of routes (cidr-nexthop pairs) advertised by the BGP Speaker.

cidr

body

string

The cidr of the route advertised by the BGP Speaker.

nexthop

body

string

The nexthop of the route advertised by the BGP Speaker.

Response Example

{
   "advertised_routes":[
      {
         "cidr":"192.168.10.0/24",
         "nexthop":"10.0.0.1"
      }
   ]
}
GET
/v2.0/bgp-speakers/{bgp-speaker-id}/bgp-dragents

List Dynamic Routing Agents hosting a specific BGP Speaker

List all BGP dynamic agents which are hosting the specified BGP Speaker.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Response Parameters

Name

In

Type

Description

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

agents

body

array

A list of agent objects.

agent_type

body

string

The type of agent such as Open vSwitch agent or DHCP agent.

alive

body

boolean

Indicates the agent is alive and running.

availability_zone

body

string

The availability zone of the agent.

binary

body

string

The executable command used to start the agent such as neutron-openvswitch-agent or neutron-dhcp-agent.

configurations

body

object

An object containing configuration specific key/value pairs; the semantics of which are determined by the binary name and type.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

description

body

string

A human-readable description for the resource.

heartbeat_timestamp

body

string

Time at which the last heartbeat was received.

host

body

string

The hostname of the system the agent is running on.

id

body

string

The ID of the resource.

resources_synced (Optional)

body

boolean

The value null means no resource view synchronization to Placement was attempted. true / false values signify the success of the last synchronization attempt. Therefore the relevant resources in Placement can only be considered up to date if this attribute is true. This attribute is read-only, it is only supposed to be updated internally, but it is readable for debugging purposes. Not all agent types track resources via Placement, therefore the value null does not necessarily means there is an error in the system.

started_at

body

string

Time at which the agent was started.

topic

body

string

The name of AMQP topic the agent is listening on such as dhcp_agent. A special value of N/A is used when the agent doesn’t use an AMQP topic.

Response Example

{
  "agents":[
     {
        "binary":"neutron-bgp-dragent",
        "description":null,
        "admin_state_up":true,
        "heartbeat_timestamp":"2016-05-17 03:05:12",
        "availability_zone":null,
        "alive":true,
        "topic":"bgp_dragent",
        "host":"yangyubj-virtual-machine",
        "agent_type":"BGP dynamic routing agent",
        "resource_versions":{
        },
        "created_at":"2016-05-09 07:38:00",
        "started_at":"2016-05-11 09:06:13",
        "id":"af216618-29d3-4ee7-acab-725bdc90e614",
        "configurations":{
           "advertise_routes":0,
           "bgp_peers":0,
           "bgp_speakers":1
        }
     }
  ]
}

BGP Peer

BGP peer defined in Neutron represents real BGP infrastructure such as routers, route reflectors and route servers.

When a BGP peer is defined and associated with a BGP Speaker, Neutron will attempt to open a BGP peering session with the mentioned remote peer. It is this session, using which Neutron announces it’s routes.

GET
/v2.0/bgp-peers

List BGP Peers

Issue a GET request to /v2.0/bgp-peers to retrieve the list of available BGP peers.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 400, 401, 403

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

bgp_peers

body

array

A list of bgp_peer objects. Each bgp_peer object represents real BGP infrastructure such as routers, route reflectors and route servers.

remote_as

body

string

The remote Autonomous System number of the BGP Peer.

name

body

string

The user meaningful name of the BGP Peer.

peer_ip

body

string

The ip address of the Peer.

id

body

string

The ID of the BGP Peer.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

Response Example

{
   "bgp_peers":[
      {
         "auth_type":"none",
         "remote_as":1001,
         "name":"bgp-peer",
         "tenant_id":"34a6e17a48cf414ebc890367bf42266b",
         "peer_ip":"10.0.0.3",
         "id":"a7193581-a31c-4ea5-8218-b3052758461f"
      }
   ]
}
GET
/v2.0/bgp-peers/{bgp-peer-id}

Show BGP Peer details

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

bgp-speaker-id

path

string

The ID of the BGP Speaker.

Response Parameters

Name

In

Type

Description

bgp_peers

body

array

A list of bgp_peer objects. Each bgp_peer object represents real BGP infrastructure such as routers, route reflectors and route servers.

remote_as

body

string

The remote Autonomous System number of the BGP Peer.

name

body

string

The user meaningful name of the BGP Peer.

peer_ip

body

string

The ip address of the Peer.

id

body

string

The ID of the BGP Peer.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

Response Example

{
   "bgp_peer":{
      "auth_type":"none",
      "remote_as":1001,
      "name":"bgp-peer",
      "tenant_id":"34a6e17a48cf414ebc890367bf42266b",
      "peer_ip":"10.0.0.3",
      "id":"a7193581-a31c-4ea5-8218-b3052758461f"
   }
}
POST
/v2.0/bgp-peers

Create a BGP Peer

Create a BGP Peer.

Normal response codes: 201

Error response codes: 401, 403, 404, 409

Request

Name

In

Type

Description

auth_type

body

object

The authentication type for the BGP Peer, can be none or md5. none by default.

remote_as

body

string

The remote Autonomous System number of the BGP Peer.

name

body

string

The user meaningful name of the BGP Peer.

peer_ip

body

string

The ip address of the Peer.

Request Example

{
   "bgp_peer":{
      "auth_type":"none",
      "remote_as":"1001",
      "name":"bgp-peer",
      "peer_ip":"10.0.0.3"
   }
}

Response Parameters

Name

In

Type

Description

bgp_peer

body

object

A BGP Peer object.

auth_type

body

object

The authentication type for the BGP Peer, can be none or md5. none by default.

password

body

string

The authentication password for the specified authentication type.

remote_as

body

string

The remote Autonomous System number of the BGP Peer.

name

body

string

The user meaningful name of the BGP Peer.

peer_ip

body

string

The ip address of the Peer.

id

body

string

The ID of the BGP Peer.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

Response Example

{
   "bgp_peer":{
      "auth_type":"none",
      "remote_as":"1001",
      "name":"bgp-peer",
      "tenant_id":"34a6e17a48cf414ebc890367bf42266b",
      "peer_ip":"10.0.0.3",
      "id":"a7193581-a31c-4ea5-8218-b3052758461f"
   }
}
PUT
/v2.0/bgp-peers/{bgp-peer-id}

Update a BGP Peer

Update a specific BGP Peer.

Normal response codes: 200

Error response codes: 400, 401, 404, 41

Request

Name

In

Type

Description

name

body

string

The user meaningful name of the BGP Peer.

password

body

string

The authentication password for the specified authentication type.

DELETE
/v2.0/bgp-peers/{bgp-peer-id}

Delete a BGP Peer

Delete a specific BGP Peer.

Normal response codes: 204

Error response codes: 400, 401, 404, 412

BGP Speaker and Dynamic Routing Agent interaction

POST
/v2.0/agents/{bgp-agent-id}/bgp-drinstances

Add BGP Speaker to a Dynamic Routing Agent

Issue a POST request to /v2.0/agents/{bgp-agent-id}/bgp-drinstances to add a BGP Speaker to the specified dynamic routing agent.

Normal response codes: 201

Request

Name

In

Type

Description

bgp_speaker_id

body

string

The ID of the BGP Speaker.

Request Example

{
    "bgp_speaker_id": "5639072c-49eb-480a-9f11-953386589bc8"
}

Response

There is no body content for the response of a successful add BGP Speaker to a Dynamic Routing Agent.

GET
/v2.0/agents/{bgp-dragent-id}/bgp-drinstances

List BGP speakers hosted by a Dynamic Routing Agent

Issue a GET request to /v2.0/agents/{bgp-dragent-id}/bgp-drinstances to list all BGP Seakers hosted on the specified dynamic routing agent.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Request

Name

In

Type

Description

bgp-dragent-id

path

string

The ID of the dynamic routing agent.

Response Parameters

Name

In

Type

Description

bgp_speakers

body

array

A list of bgp_speaker objects. Each bgp_speaker object acts as a route server using BGP routing protocol.

id

body

string

The ID of the BGP Speaker.

peers

body

array

A list of bgp_peer objects. Each bgp_peer object represents real BGP infrastructure such as routers, route reflectors and route servers.

name

body

string

The user meaningful name of the BGP Speaker.

ip_version

body

string

The IP version (4 or 6) of the BGP Speaker.

advertise_floating_ip_host_routes

body

string

Whether to enable or disable the advertisement of floating ip host routes by the BGP Speaker. True by default.

advertise_tenant_networks

body

string

Whether to enable or disable the advertisement of tenant network routes by the BGP Speaker. True by default.

local_as

body

string

The local Autonomous System number of the BGP Speaker.

networks

body

string

The ID of the network to which the BGP Speaker is associated.

project_id

body

string

The ID of the project.

Response Example

{
     "bgp_speakers":[
        {
           "peers":[
           ],
           "name":"bgp-speaker",
           "tenant_id":"34a6e17a48cf414ebc890367bf42266b",
           "local_as":1000,
           "advertise_tenant_networks":true,
           "networks":[
           ],
           "ip_version":4,
           "advertise_floating_ip_host_routes":true,
           "id":"b759b2a1-27f4-4a6b-bb61-f2c9a22c9902"
        }
     ]
}
DELETE
/v2.0/agents/{bgp-agent-id}/bgp-drinstances/{bgp-speaker-id}

Delete BGP Speaker from a Dynamic Routing Agent

Issue a DELETE request to /v2.0/agents/{bgp-agent-id}/bgp-drinstances/{bgp-speaker-id} to delete the BGP Speaker hosted by the specified dynamic routing agent.

Normal response codes: 204

Request

Name

In

Type

Description

bgp-speaker-id

path

string

The ID of the BGP Speaker.

bgp-dragent-id

path

string

The ID of the dynamic routing agent.

Response

There is no body content for the response of a successful DELETE request.

Logging

Log resource

The logging extension lists, creates, shows information for, and updates log resource.

Resource timestamps

The standard-attr-timestamp extension adds the created_at and updated_at attributes to all resources that have standard attributes.

GET
/v2.0/log/logs

List logs

Lists all log resources associated with your project.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

The list might be empty.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

id (Optional)

query

string

Filter the list result by the ID of the resource.

name (Optional)

query

string

Filter the list result by the human-readable name of the resource.

description (Optional)

query

string

Filter the list result by the human-readable description of the resource.

tenant_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

project_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

event (Optional)

query

string

Filter the log list result by the type of security events, which is ACCEPT, DROP, or ALL.

revision_number (Optional)

query

integer

Filter the list result by the revision number of the resource.

resource_type (Optional)

query

string

Filter the log list result by the resource type such as security_group.

resource_id (Optional)

query

string

Filter the log list result by the ID of resource (e.g security group ID).

target_id (Optional)

query

string

Filter the log list result by the ID of resource that is the logging target.

enabled (Optional)

query

boolean

Filter the log list result based on this log object is enabled (true) or disabled (false).

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by a log attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • enabled

  • event

  • id

  • name

  • project_id

  • resource_id

  • resource_type

  • target_id

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

logs

body

array

A list of log objects.

id

body

string

The ID of the log object.

name

body

string

Human-readable name of the resource.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

description

body

string

A human-readable description for the resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

event

body

string

Type of security events to log. ACCEPT, DROP, or ALL.

revision_number

body

integer

The revision number of the resource.

resource_type

body

string

The resource log type such as ‘security_group’.

resource_id

body

string

The ID of resource log (e.g security group ID).

target_id

body

string

The ID of resource target log such as port ID.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

enabled

body

boolean

Indicates whether this log object is enabled or disabled.

Response Example

{
    "logs": [
        {
            "name": "security group log",
            "description": "Log for project demo.",
            "id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
            "project_id": "92a5a4f4245a4abbafacb7ca73b027b0",
            "tenant_id": "92a5a4f4245a4abbafacb7ca73b027b0",
            "created_at": "2018-04-03T21:03:04Z",
            "updated_at": "2018-04-03T21:03:04Z",
            "enabled": true,
            "revision_number": 1,
            "resource_type": "security_group",
            "resource_id": null,
            "target_id": null,
            "event": "ALL"
        }
    ]
}
POST
/v2.0/log/logs

Create log

Creates a log resource.

Creates a log resource by using the configuration that you define in the request object. A response object is returned. The object contains a unique ID.

If the caller is not an administrative user, this call returns the HTTP Forbidden (403) response code.

Users with an administrative role can create policies on behalf of other projects by specifying a project ID that is different than their own.

Normal response codes: 201

Error response codes: 400, 401, 403, 409

Request

Name

In

Type

Description

log

body

object

A log object.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

tenant_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

project_id (Optional)

body

string

The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.

event (Optional)

body

string

Type of security events to log. ACCEPT, DROP, or ALL. Default is ALL.

resource_type

body

string

The resource log type such as ‘security_group’.

resource_id (Optional)

body

string

The ID of resource log (e.g security group ID).

target_id (Optional)

body

string

The ID of resource target log such as port ID.

enabled (Optional)

body

boolean

Indicates whether this log object is enabled or disabled. Default is true.

Request Example

{
    "log": {
        "name": "security group log",
        "description": "Log for project demo.",
        "resource_type": "security_group"
    }
}

Response Parameters

Name

In

Type

Description

log

body

object

A log object.

id

body

string

The ID of the log object.

name

body

string

Human-readable name of the resource.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

description

body

string

A human-readable description for the resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

event

body

string

Type of security events to log. ACCEPT, DROP, or ALL.

revision_number

body

integer

The revision number of the resource.

resource_type

body

string

The resource log type such as ‘security_group’.

resource_id

body

string

The ID of resource log (e.g security group ID).

target_id

body

string

The ID of resource target log such as port ID.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

enabled

body

boolean

Indicates whether this log object is enabled or disabled.

Request Example

{
    "log": {
        "name": "security group log",
        "description": "Log for project demo.",
        "id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
        "project_id": "92a5a4f4245a4abbafacb7ca73b027b0",
        "tenant_id": "92a5a4f4245a4abbafacb7ca73b027b0",
        "created_at": "2018-04-03T21:03:04Z",
        "updated_at": "2018-04-03T21:03:04Z",
        "enabled": true,
        "resource_type": "security_group",
        "resource_id": null,
        "revision_number": 1,
        "target_id": null,
        "event": "ALL"
    }
}
GET
/v2.0/log/logs/{log_id}

Show log

Shows details log resource.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

log_id

path

string

The ID of the log resource.

Response Parameters

Name

In

Type

Description

log

body

object

A log object.

id

body

string

The ID of the log object.

name

body

string

Human-readable name of the resource.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

description

body

string

A human-readable description for the resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

event

body

string

Type of security events to log. ACCEPT, DROP, or ALL.

revision_number

body

integer

The revision number of the resource.

resource_type

body

string

The resource log type such as ‘security_group’.

resource_id

body

string

The ID of resource log (e.g security group ID).

target_id

body

string

The ID of resource target log such as port ID.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

enabled

body

boolean

Indicates whether this log object is enabled or disabled.

Response Example

{
    "log": {
        "name": "security group log",
        "description": "Log for project demo.",
        "id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
        "project_id": "8d4c70a21fed4aeba121a1a429ba0d04",
        "tenant_id": "8d4c70a21fed4aeba121a1a429ba0d04",
        "created_at": "2018-04-03T21:03:04Z",
        "updated_at": "2018-04-03T21:03:04Z",
        "enabled": true,
        "revision_number": 1,
        "resource_type": "security_group",
        "resource_id": null,
        "target_id": null,
        "event": "ACCEPT"
    }
}
PUT
/v2.0/log/logs/{log_id}

Update log

Updates a log resource.

Normal response codes: 200

Error response codes: 400, 401, 404, 412

Request

Name

In

Type

Description

log_id

path

string

The ID of the log resource.

log

body

object

A log object.

name (Optional)

body

string

Human-readable name of the resource. Default is an empty string.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

enabled (Optional)

body

boolean

Indicates whether this log object is enabled or disabled.

Request Example

{
    "log": {
        "enabled": false
    }
}

Response Parameters

Name

In

Type

Description

log

body

object

A log object.

id

body

string

The ID of the log object.

name

body

string

Human-readable name of the resource.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

description

body

string

A human-readable description for the resource.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

event

body

string

Type of security events to log. ACCEPT, DROP, or ALL.

revision_number

body

integer

The revision number of the resource.

resource_type

body

string

The resource log type such as ‘security_group’.

resource_id

body

string

The ID of resource log (e.g security group ID).

target_id

body

string

The ID of resource target log such as port ID.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

enabled

body

boolean

Indicates whether this log object is enabled or disabled.

Response Example

{
    "log": {
        "name": "security group log",
        "description": "Log for project demo.",
        "id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
        "project_id": "8d4c70a21fed4aeba121a1a429ba0d04",
        "tenant_id": "8d4c70a21fed4aeba121a1a429ba0d04",
        "created_at": "2018-04-03T21:03:04Z",
        "updated_at": "2018-04-03T21:03:04Z",
        "enabled": false,
        "revision_number": 3,
        "resource_type": "security_group",
        "resource_id": null,
        "target_id": null,
        "event": "DROP"
    }
}
DELETE
/v2.0/log/logs/{log_id}

Delete log

Deletes a log resource.

Normal response codes: 204

Error response codes: 400, 401, 404, 412

Request

Name

In

Type

Description

log_id

path

string

The ID of the log resource.

Response

There is no body content for the response of a successful DELETE request.

Loggable resource

GET
/v2.0/log/loggable-resources

List loggable resources

Lists all resource log types are supporting.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Response Parameters

Name

In

Type

Description

loggable_resources

body

object

A list of loggable_resource object.

type

body

string

The resource log type such as ‘security_group’.

Response Example

{
    "loggable_resources": [
        {
            "type": "security_group"
        }
    ]
}

Networking Agents

Agents

Lists, shows details for, updates, and deletes agents.

Agent Resources Synced Extension

The agent-resources-synced extension adds the resources_synced attribute to agents.

Availability Zone Extension

The availability_zone extension adds the availability_zone attribute to agents. availability_zone is the name of the availability zone that the agent is running on.

GET
/v2.0/agents

List all agents

Lists all agents.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

admin_state_up (Optional)

query

boolean

Filter the list result by the administrative state of the resource, which is up (true) or down (false).

agent_type (Optional)

query

string

Filter the list result by the type of agent such as Open vSwitch agent or DHCP agent.

alive (Optional)

query

boolean

Filter the list result based on whether the agent is alive and running.

availability_zone (Optional)

query

string

Filter the list result by the availability zone of the agent.

binary (Optional)

query

string

Filter the list result by the executable command used to start the agent such as neutron-openvswitch-agent or neutron-dhcp-agent.

description (Optional)

query

string

Filter the list result by the human-readable description of the resource.

host (Optional)

query

string

Filter the list result by the hostname of the system the agent is running on.

id (Optional)

query

string

Filter the list result by the ID of the resource.

topic (Optional)

query

string

Filter the list result by the name of AMQP topic the agent is listening on such as dhcp_agent.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

sort_dir (Optional)

query

string

Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.

sort_key (Optional)

query

string

Sorts by agent attributes. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • admin_state_up

  • agent_type

  • alive

  • binary

  • created_at

  • description

  • heartbeat_timestamp

  • host

  • id

  • started_at

  • topic

Response Parameters

Name

In

Type

Description

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

agents

body

array

A list of agent objects.

agent_type

body

string

The type of agent such as Open vSwitch agent or DHCP agent.

alive

body

boolean

Indicates the agent is alive and running.

availability_zone

body

string

The availability zone of the agent.

binary

body

string

The executable command used to start the agent such as neutron-openvswitch-agent or neutron-dhcp-agent.

configurations

body

object

An object containing configuration specific key/value pairs; the semantics of which are determined by the binary name and type.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

description

body

string

A human-readable description for the resource.

heartbeat_timestamp

body

string

Time at which the last heartbeat was received.

host

body

string

The hostname of the system the agent is running on.

id

body

string

The ID of the resource.

resources_synced (Optional)

body

boolean

The value null means no resource view synchronization to Placement was attempted. true / false values signify the success of the last synchronization attempt. Therefore the relevant resources in Placement can only be considered up to date if this attribute is true. This attribute is read-only, it is only supposed to be updated internally, but it is readable for debugging purposes. Not all agent types track resources via Placement, therefore the value null does not necessarily means there is an error in the system.

started_at

body

string

Time at which the agent was started.

topic

body

string

The name of AMQP topic the agent is listening on such as dhcp_agent. A special value of N/A is used when the agent doesn’t use an AMQP topic.

Response Example

{
    "agents": [
        {
            "binary": "neutron-openvswitch-agent",
            "description": null,
            "availability_zone": null,
            "heartbeat_timestamp": "2017-09-12 19:40:08",
            "admin_state_up": true,
            "alive": true,
            "id":" 04c62b91-b799-48b7-9cd5-2982db6df9c6",
            "topic": "N/A",
            "host": "agenthost1",
            "agent_type": "Open vSwitch agent",
            "started_at": "2017-09-12 19:35:38",
            "created_at": "2017-09-12 19:35:38",
            "resources_synced": true,
            "configurations": {
                "ovs_hybrid_plug": true,
                "in_distributed_mode": false,
                "datapath_type": "system",
                "vhostuser_socket_dir": "/var/run/openvswitch",
                "tunneling_ip": "172.16.78.191",
                "arp_responder_enabled": false,
                "devices": 0,
                "ovs_capabilities": {
                    "datapath_types": [
                        "netdev",
                        "system"
                    ],
                    "iface_types": [
                        "geneve",
                        "gre",
                        "internal",
                        "ipsec_gre",
                        "lisp",
                        "patch",
                        "stt",
                        "system",
                        "tap",
                        "vxlan"
                    ]
                },
                "log_agent_heartbeats": false,
                "l2_population": false,
                "tunnel_types": [
                    "vxlan"
                ],
                "extensions": [

                ],
                "enable_distributed_routing": false,
                "bridge_mappings": {
                    "public": "br-ex"
                }
            }
        },
        {
            "binary": "neutron-dhcp-agent",
            "description": null,
            "availability_zone": "nova",
            "heartbeat_timestamp": "2017-09-12 19:39:56",
            "admin_state_up": true,
            "alive": true,
            "id": "840d5d68-5759-4e9e-812f-f3bd19214c7f",
            "topic": "dhcp_agent",
            "host": "agenthost1",
            "agent_type" :"DHCP agent",
            "started_at": "2017-09-12 19:35:36",
            "created_at": "2017-09-12 19:35:36",
            "resources_synced": null,
            "configurations": {
                "subnets": 2,
                "dhcp_lease_duration": 86400,
                "dhcp_driver": "neutron.agent.linux.dhcp.Dnsmasq",
                "networks": 1,
                "log_agent_heartbeats": false,
                "ports": 3
            }
        },
        {
            "binary": "neutron-l3-agent",
            "description": null,
            "availability_zone": "nova",
            "heartbeat_timestamp": "2017-09-12 19:40:08",
            "admin_state_up": true,
            "alive": true,
            "id": "a09b81fc-5a42-46d3-a306-1a5d122a7787",
            "topic": "l3_agent",
            "host": "agenthost1",
            "agent_type": "L3 agent",
            "started_at": "2017-09-12 19:35:38",
            "created_at": "2017-09-12 19:35:38",
            "resources_synced": null,
            "configurations": {
                "agent_mode": "legacy",
                "gateway_external_network_id": "",
                "handle_internal_only_routers": true,
                "routers": 1,
                "interfaces": 2,
                "floating_ips": 0,
                "interface_driver": "openvswitch",
                "log_agent_heartbeats": false,
                "ex_gw_ports": 1
            }
        },
        {
            "binary": "neutron-metadata-agent",
            "description": null,
            "availability_zone": null,
            "heartbeat_timestamp": "2017-09-12 19:40:09",
            "admin_state_up": true,
            "alive": true,
            "id": "c876c9f7-1058-4b9b-90ed-20fb3f905ec4",
            "topic": "N/A",
            "host": "agenthost1",
            "agent_type": "Metadata agent",
            "started_at": "2017-09-12 19:35:39",
            "created_at": "2017-09-12 19:35:39",
            "resources_synced": null,
            "configurations": {
                "log_agent_heartbeats": false,
                "nova_metadata_host": "172.16.78.191",
                "nova_metadata_port": 8775,
                "metadata_proxy_socket": "/opt/stack/data/neutron/metadata_proxy"
            }
        }
    ]
}
GET
/v2.0/agents/{agent_id}

Show agent details

Shows details for an agent.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

agent_id

path

string

The ID of the agent.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

agent

body

string

An agent object.

agent_type

body

string

The type of agent such as Open vSwitch agent or DHCP agent.

alive

body

boolean

Indicates the agent is alive and running.

availability_zone

body

string

The availability zone of the agent.

binary

body

string

The executable command used to start the agent such as neutron-openvswitch-agent or neutron-dhcp-agent.

configurations

body

object

An object containing configuration specific key/value pairs; the semantics of which are determined by the binary name and type.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

description

body

string

A human-readable description for the resource.

heartbeat_timestamp

body

string

Time at which the last heartbeat was received.

host

body

string

The hostname of the system the agent is running on.

id

body

string

The ID of the resource.

resources_synced (Optional)

body

boolean

The value null means no resource view synchronization to Placement was attempted. true / false values signify the success of the last synchronization attempt. Therefore the relevant resources in Placement can only be considered up to date if this attribute is true. This attribute is read-only, it is only supposed to be updated internally, but it is readable for debugging purposes. Not all agent types track resources via Placement, therefore the value null does not necessarily means there is an error in the system.

started_at

body

string

Time at which the agent was started.

topic

body

string

The name of AMQP topic the agent is listening on such as dhcp_agent. A special value of N/A is used when the agent doesn’t use an AMQP topic.

Response Example

{
    "agent": {
        "binary": "neutron-openvswitch-agent",
        "description": null,
        "availability_zone": null,
        "heartbeat_timestamp": "2017-09-12 19:40:38",
        "admin_state_up": true,
        "alive": true,
        "id": "04c62b91-b799-48b7-9cd5-2982db6df9c6",
        "topic": "N/A",
        "host": "agenthost1",
        "agent_type": "Open vSwitch agent",
        "started_at": "2017-09-12 19:35:38",
        "created_at": "2017-09-12 19:35:38",
        "resources_synced": true,
        "configurations": {
            "ovs_hybrid_plug": true,
            "in_distributed_mode": false,
            "datapath_type": "system",
            "vhostuser_socket_dir": "/var/run/openvswitch",
            "tunneling_ip": "172.16.78.191",
            "arp_responder_enabled": false,
            "devices": 0,
            "ovs_capabilities": {
                "datapath_types": [
                    "netdev",
                    "system"
                ],
                "iface_types": [
                    "geneve",
                    "gre",
                    "internal",
                    "ipsec_gre",
                    "lisp",
                    "patch",
                    "stt",
                    "system",
                    "tap",
                    "vxlan"
                ]
            },
            "log_agent_heartbeats": false,
            "l2_population": false,
            "tunnel_types": [
                "vxlan"
            ],
            "extensions": [],
            "enable_distributed_routing": false,
            "bridge_mappings": {
                "public": "br-ex"
            }
        }
    }
}
PUT
/v2.0/agents/{agent_id}

Update agent

Updates an agent.

Normal response codes: 200

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

agent_id

path

string

The ID of the agent.

admin_state_up (Optional)

body

boolean

The administrative state of the resource, which is up (true) or down (false). Default is true.

description (Optional)

body

string

A human-readable description for the resource. Default is an empty string.

Request Example

{
    "agent": {
        "description": "My OVS agent for OpenStack"
    }
}

Response Parameters

Name

In

Type

Description

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

agent

body

string

An agent object.

agent_type

body

string

The type of agent such as Open vSwitch agent or DHCP agent.

alive

body

boolean

Indicates the agent is alive and running.

availability_zone

body

string

The availability zone of the agent.

binary

body

string

The executable command used to start the agent such as neutron-openvswitch-agent or neutron-dhcp-agent.

configurations

body

object

An object containing configuration specific key/value pairs; the semantics of which are determined by the binary name and type.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

description

body

string

A human-readable description for the resource.

heartbeat_timestamp

body

string

Time at which the last heartbeat was received.

host

body

string

The hostname of the system the agent is running on.

id

body

string

The ID of the resource.

resources_synced (Optional)

body

boolean

The value null means no resource view synchronization to Placement was attempted. true / false values signify the success of the last synchronization attempt. Therefore the relevant resources in Placement can only be considered up to date if this attribute is true. This attribute is read-only, it is only supposed to be updated internally, but it is readable for debugging purposes. Not all agent types track resources via Placement, therefore the value null does not necessarily means there is an error in the system.

started_at

body

string

Time at which the agent was started.

topic

body

string

The name of AMQP topic the agent is listening on such as dhcp_agent. A special value of N/A is used when the agent doesn’t use an AMQP topic.

Response Example

{
    "agent": {
        "binary": "neutron-openvswitch-agent",
        "description": "My OVS agent for OpenStack",
        "availability_zone": null,
        "heartbeat_timestamp": "2017-09-12 19:40:38",
        "admin_state_up": true,
        "alive": true,
        "id": "04c62b91-b799-48b7-9cd5-2982db6df9c6",
        "topic": "N/A",
        "host": "agenthost1",
        "agent_type": "Open vSwitch agent",
        "started_at": "2017-09-12 19:35:38",
        "created_at": "2017-09-12 19:35:38",
        "resources_synced": true,
        "configurations": {
            "ovs_hybrid_plug": true,
            "in_distributed_mode": false,
            "datapath_type": "system",
            "vhostuser_socket_dir": "/var/run/openvswitch",
            "tunneling_ip": "172.16.78.191",
            "arp_responder_enabled": false,
            "devices": 0,
            "ovs_capabilities": {
                "datapath_types": [
                    "netdev",
                    "system"
                ],
                "iface_types": [
                    "geneve",
                    "gre",
                    "internal",
                    "ipsec_gre",
                    "lisp",
                    "patch",
                    "stt",
                    "system",
                    "tap",
                    "vxlan"
                ]
            },
            "log_agent_heartbeats": false,
            "l2_population": false,
            "tunnel_types": [
                "vxlan"
            ],
            "extensions": [],
            "enable_distributed_routing": false,
            "bridge_mappings": {
                "public": "br-ex"
            }
        }
    }
}
DELETE
/v2.0/agents/{agent_id}

Delete agent

Agents that won’t be used anymore can be removed. Before deleting agents via API, the agent should be stopped/disabled.

Normal response codes: 204

Error response codes: 401, 404, 409

Request

Name

In

Type

Description

agent_id

path

string

The ID of the agent.

Response

There is no body content for the response of a successful DELETE request.

Availability Zones

Lists availability zones.

GET
/v2.0/availability_zones

List all availability zones

Lists all availability zones.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request

Name

In

Type

Description

state (Optional)

query

string

Filter the list result by the state of the availability zone, which is either available or unavailable.

resource (Optional)

query

string

Filter the list result by the resource type of the availability zone. The supported resource types are network and router.

name (Optional)

query

string

Filter the list result by the human-readable name of the resource.

Response Parameters

Name

In

Type

Description

availability_zones

body

array

A list of availability zone objects.

state

body

string

The state of the availability zone, which is either available or unavailable.

resource

body

string

The resource type of the availability zone. The supported resource types are network and router.

name

body

string

Human-readable name of the resource.

Response Example

{
    "availability_zones": [
        {
            "state": "available",
            "resource": "router",
            "name": "nova"
        },
        {
            "state": "available",
            "resource": "network",
            "name": "nova"
        }
    ]
}

L3 agent scheduler

The L3 agent scheduler extension (l3_agent_scheduler) allows administrators to assign Neutron routers to Neutron L3 agents, and retrieve mappings between Neutron routers and L3 agents.

GET
/v2.0/agents/{agent_id}/l3-routers

List routers hosted by an L3 agent

Lists routers that an l3 agent hosts.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

agent_id

path

string

The ID of the agent.

Response Parameters

Name

In

Type

Description

routers

body

array

A list of router objects.

id

body

string

The ID of the router.

tenant_id

body

string

The ID of the project.

project_id

body

string

The ID of the project.

name

body

string

Human-readable name of the resource.

description

body

string

A human-readable description for the resource.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

status

body

string

The router status.

external_gateway_info

body

object

The external gateway information of the router. If the router has an external gateway, this would be a dict with network_id, enable_snat, external_fixed_ips, qos_policy_id, enable_default_route_ecmp and enable_default_route_bfd. Otherwise, this would be null.

revision_number

body

integer

The revision number of the resource.

routes

body

array

The extra routes configuration for L3 router. A list of dictionaries with destination and nexthop parameters. It is available when extraroute extension is enabled.

destination

body

string

The destination CIDR.

nexthop

body

string

The IP address of the next hop for the corresponding destination. The next hop IP address must be a part of one of the subnets to which the router interfaces are connected.

distributed

body

boolean

true indicates a distributed router. It is available when dvr extension is enabled.

ha

body

boolean

true indicates a highly-available router. It is available when l3-ha extension is enabled.

availability_zone_hints

body

array

The availability zone candidates for the router. It is available when router_availability_zone extension is enabled.

availability_zones

body

array

The availability zone(s) for the router. It is available when router_availability_zone extension is enabled.

service_type_id

body

string

The ID of the service type associated with the router.

flavor_id

body

string

The ID of the flavor associated with the router.

Response Example

{
    "routers": [
        {
            "admin_state_up": true,
            "availability_zone_hints": [],
            "availability_zones": [
                "nova"
            ],
            "description": "",
            "distributed": false,
            "external_gateway_info": {
                "enable_snat": true,
                "external_fixed_ips": [
                    {
                        "ip_address": "172.24.4.3",
                        "subnet_id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf"
                    },
                    {
                        "ip_address": "2001:db8::c",
                        "subnet_id": "0c56df5d-ace5-46c8-8f4c-45fa4e334d18"
                    }
                ],
                "network_id": "ae34051f-aa6c-4c75-abf5-50dc9ac99ef3"
            },
            "flavor_id": "f7b14d9a-b0dc-4fbe-bb14-a0f4970a69e0",
            "ha": false,
            "id": "915a14a6-867b-4af7-83d1-70efceb146f9",
            "name": "router2",
            "revision_number": 1,
            "routes": [
                {
                    "destination": "179.24.1.0/24",
                    "nexthop": "172.24.3.99"
                }
            ],
            "status": "ACTIVE",
            "project_id": "0bd18306d801447bb457a46252d82d13",
            "tenant_id": "0bd18306d801447bb457a46252d82d13",
            "service_type_id": null
        },
        {
            "admin_state_up": true,
            "availability_zone_hints": [],
            "availability_zones": [
                "nova"
            ],
            "description": "",
            "distributed": false,
            "external_gateway_info": {
                "enable_snat": true,
                "external_fixed_ips": [
                    {
                        "ip_address": "172.24.4.6",
                        "subnet_id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf"
                    },
                    {
                        "ip_address": "2001:db8::9",
                        "subnet_id": "0c56df5d-ace5-46c8-8f4c-45fa4e334d18"
                    }
                ],
                "network_id": "ae34051f-aa6c-4c75-abf5-50dc9ac99ef3"
            },
            "flavor_id": "f7b14d9a-b0dc-4fbe-bb14-a0f4970a69e0",
            "ha": false,
            "id": "f8a44de0-fc8e-45df-93c7-f79bf3b01c95",
            "name": "router1",
            "revision_number": 1,
            "routes": [],
            "status": "ACTIVE",
            "project_id": "0bd18306d801447bb457a46252d82d13",
            "tenant_id": "0bd18306d801447bb457a46252d82d13",
            "service_type_id": null
        }
    ]
}
POST
/v2.0/agents/{agent_id}/l3-routers

Schedule router to an l3 agent

Add a router to an l3 agent.

Normal response codes: 201

Error response codes: 400, 401, 404

Request

Name

In

Type

Description

agent_id

path

string

The ID of the agent.

router_id

body

string

The ID of the router.

Request Example

{
  "router_id": "43e66290-79a4-415d-9eb9-7ff7919839e1"
}

Response Parameters

null

Response Example

There is no body content for the response of a successful POST request.

DELETE
/v2.0/agents/{agent_id}/l3-routers/{router_id}

Remove l3 router from an l3 agent

Removes a router from an l3 agent.

Normal response codes: 204

Error response codes: 401, 404

Request

Name

In

Type

Description

agent_id

path

string

The ID of the agent.

router_id

path

string

The ID of the router.

Response Example

There is no body content for the response of a successful DELETE request.

GET
/v2.0/routers/{router_id}/l3-agents

List L3 agents hosting a router

Lists l3 agents hosting a specific router.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

router_id

path

string

The ID of the router.

Response Parameters

Name

In

Type

Description

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

agents

body

array

A list of agent objects.

agent_type

body

string

The type of agent such as Open vSwitch agent or DHCP agent.

alive

body

boolean

Indicates the agent is alive and running.

binary

body

string

The executable command used to start the agent such as neutron-openvswitch-agent or neutron-dhcp-agent.

configurations

body

object

An object containing configuration specific key/value pairs; the semantics of which are determined by the binary name and type.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

description

body

string

A human-readable description for the resource.

heartbeat_timestamp

body

string

Time at which the last heartbeat was received.

host

body

string

The hostname of the system the agent is running on.

id

body

string

The ID of the resource.

started_at

body

string

Time at which the agent was started.

topic

body

string

The name of AMQP topic the agent is listening on such as dhcp_agent. A special value of N/A is used when the agent doesn’t use an AMQP topic.

Response Example

{
    "agents": [
        {
            "binary": "neutron-l3-agent",
            "description": null,
            "availability_zone": "nova",
            "heartbeat_timestamp": "2018-04-08 07:32:42",
            "admin_state_up": true,
            "alive": true,
            "topic": "l3_agent",
            "host": "mkm-instance01",
            "ha_state": null,
            "agent_type": "L3 agent",
            "resource_versions": {},
            "created_at": "2018-03-11 08:10:58",
            "started_at": "2018-03-11 08:10:58",
            "id": "b64f5c61-2210-41a6-869f-b51d7914511e",
            "configurations": {
                "agent_mode": "legacy",
                "gateway_external_network_id": "",
                "handle_internal_only_routers": true,
                "routers": 3,
                "interfaces": 1,
                "floating_ips": 0,
                "interface_driver": "openvswitch",
                "log_agent_heartbeats": false,
                "ex_gw_ports": 1
            }
        }
    ]
}

DHCP agent scheduler

The DHCP agent scheduler extension (dhcp_agent_scheduler) enables administrators to assign DHCP servers for Neutron networks to given Neutron DHCP agents, and retrieve mappings between Neutron networks and DHCP agents.

GET
/v2.0/agents/{agent_id}/dhcp-networks

List networks hosted by a DHCP agent

Lists networks that a DHCP agent hosts.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401, 403

Request

Name

In

Type

Description

agent_id

path

string

The ID of the agent.

Response Parameters

Name

In

Type

Description

network

body

object

A network object.

admin_state_up

body

boolean

The administrative state of the network, which is up (true) or down (false).

availability_zone_hints

body

array

The availability zone candidate for the network.

availability_zones

body

array

The availability zone for the network.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

dns_domain

body

string

A valid DNS domain.

id

body

string

The ID of the network.

ipv4_address_scope

body

string

The ID of the IPv4 address scope that the network is associated with.

ipv6_address_scope

body

string

The ID of the IPv6 address scope that the network is associated with.

l2_adjacency

body

boolean

Indicates whether L2 connectivity is available throughout the network.

mtu

body

integer

The maximum transmission unit (MTU) value to address fragmentation. Minimum value is 68 for IPv4, and 1280 for IPv6.

name

body

string

Human-readable name of the network.

port_security_enabled

body

boolean

The port security status of the network. Valid values are enabled (true) and disabled (false). This value is used as the default value of port_security_enabled field of a newly created port.

project_id

body

string

The ID of the project.

provider:network_type

body

string

The type of physical network that this network is mapped to. For example, flat, vlan, vxlan, or gre. Valid values depend on a networking back-end.

provider:physical_network

body

string

The physical network where this network/segment is implemented.

provider:segmentation_id

body

integer

The ID of the isolated segment on the physical network. The network_type attribute defines the segmentation model. For example, if the network_type value is vlan, this ID is a vlan identifier. If the network_type value is gre, this ID is a gre key. Note that only the segmentation-id of VLAN type networks can be changed!

qos_policy_id

body

string

The ID of the QoS policy.

revision_number

body

integer

The revision number of the resource.

router:external

body

boolean

Defines whether the network may be used for creation of floating IPs. Only networks with this flag may be an external gateway for routers. The network must have an external routing facility that is not managed by the networking service. If the network is updated from external to internal the unused floating IPs of this network are automatically deleted when extension floatingip-autodelete-internal is present.

segments

body

array

A list of provider segment objects.

shared

body

boolean

Indicates whether this network is shared across all tenants. By default, only administrative users can change this value.

status

body

string

The network status. Values are ACTIVE, DOWN, BUILD or ERROR.

subnets

body

array

The associated subnets.

tenant_id

body

string

The ID of the project.

updated_at

body

string

Time at which the resource has been updated (in UTC ISO8601 format).

vlan_transparent

body

boolean

Indicates the VLAN transparency mode of the network, which is VLAN transparent (true) or not VLAN transparent (false).

description

body

string

A human-readable description for the resource.

is_default

body

boolean

The network is default pool or not.

Response Example

{
    "networks": [
        {
            "admin_state_up": true,
            "availability_zone_hints": [],
            "availability_zones": [
                "nova"
            ],
            "created_at": "2016-03-08T20:19:41",
            "dns_domain": "my-domain.org.",
            "id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
            "ipv4_address_scope": null,
            "ipv6_address_scope": null,
            "l2_adjacency": false,
            "mtu": 1500,
            "name": "net1",
            "port_security_enabled": true,
            "project_id": "4fd44f30292945e481c7b8a0c8908869",
            "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e",
            "revision_number": 1,
            "router:external": false,
            "shared": false,
            "status": "ACTIVE",
            "subnets": [
                "54d6f61d-db07-451c-9ab3-b9609b6b6f0b"
            ],
            "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
            "updated_at": "2016-03-08T20:19:41",
            "vlan_transparent": true,
            "description": "",
            "is_default": false
        },
        {
            "admin_state_up": true,
            "availability_zone_hints": [],
            "availability_zones": [
                "nova"
            ],
            "created_at": "2016-03-08T20:19:41",
            "dns_domain": "my-domain.org.",
            "id": "db193ab3-96e3-4cb3-8fc5-05f4296d0324",
            "ipv4_address_scope": null,
            "ipv6_address_scope": null,
            "l2_adjacency": false,
            "mtu": 1500,
            "name": "net2",
            "port_security_enabled": true,
            "project_id": "26a7980765d0414dbc1fc1f88cdb7e6e",
            "qos_policy_id": "bfdb6c39f71e4d44b1dfbda245c50819",
            "revision_number": 3,
            "router:external": false,
            "shared": false,
            "status": "ACTIVE",
            "subnets": [
                "08eae331-0402-425a-923c-34f7cfe39c1b"
            ],
            "tenant_id": "26a7980765d0414dbc1fc1f88cdb7e6e",
            "updated_at": "2016-03-08T20:19:41",
            "vlan_transparent": false,
            "description": "",
            "is_default": false
        }
    ]
}
POST
/v2.0/agents/{agent_id}/dhcp-networks

Schedule a network to a DHCP agent

Add a network to a DHCP agent

Normal response codes: 201

Error response codes: 400, 403, 409, 404

Request

Name

In

Type

Description

agent_id

path

string

The ID of the agent.

network_id

body

string

The ID of the network.

Request Example

{"network_id": "1ae075ca-708b-4e66-b4a7-b7698632f05f"}

Response Parameters

null

Response Example

There is no body content for the response of a successful POST request.

DELETE
/v2.0/agents/{agent_id}/dhcp-networks/{network_id}

Remove network from a DHCP agent

Removes a network from a dhcp agent.

Normal response codes: 204

Error response codes: 401, 403, 404, 409

Request

Name

In

Type

Description

agent_id

path

string

The ID of the agent.

network_id

body

string

The ID of the attached network.

Response Example

There is no body content for the response of a successful DELETE request.

GET
/v2.0/networks/{network_id}/dhcp-agents

List DHCP agents hosting a network

Lists DHCP agents hosting a network.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401, 403

Request

Name

In

Type

Description

network_id

body

string

The ID of the attached network.

Response Parameters

Name

In

Type

Description

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

agents

body

array

A list of agent objects.

agent_type

body

string

The type of agent such as Open vSwitch agent or DHCP agent.

alive

body

boolean

Indicates the agent is alive and running.

binary

body

string

The executable command used to start the agent such as neutron-openvswitch-agent or neutron-dhcp-agent.

configurations

body

object

An object containing configuration specific key/value pairs; the semantics of which are determined by the binary name and type.

created_at

body

string

Time at which the resource has been created (in UTC ISO8601 format).

description

body

string

A human-readable description for the resource.

heartbeat_timestamp

body

string

Time at which the last heartbeat was received.

host

body

string

The hostname of the system the agent is running on.

id

body

string

The ID of the resource.

started_at

body

string

Time at which the agent was started.

topic

body

string

The name of AMQP topic the agent is listening on such as dhcp_agent. A special value of N/A is used when the agent doesn’t use an AMQP topic.

Response Example

{
    "agents": [
        {
            "binary": "neutron-dhcp-agent",
            "description": null,
            "availability_zone": "nova",
            "heartbeat_timestamp": "2018-04-08 07:32:42",
            "admin_state_up": true,
            "alive": true,
            "topic": "dhcp_agent",
            "host": "mkm-instance01",
            "ha_state": null,
            "agent_type": "DHCP agent",
            "resource_versions": {},
            "created_at": "2018-03-11 08:10:58",
            "started_at": "2018-03-11 08:10:58",
            "id": "b64f5c61-2210-41a6-869f-b51d7914511e",
            "configurations": {
              "subnets": 1,
              "dhcp_lease_duration": 86400,
              "dhcp_driver": "neutron.agent.linux.dhcp.Dnsmasq",
              "ports": 2,
              "log_agent_heartbeats": false,
              "networks": 1
            }
        }
    ]
}

Auto Allocated Topology

Auto Allocated Topologies

Show details and delete the auto allocated topology for a given project. This API is only available when the auto-allocated-topology extension is enabled.

GET
/v2.0/auto-allocated-topology/{project_id}

Show auto allocated topology details

Shows details for an auto allocated topology.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request

Name

In

Type

Description

project_id

path

string

The ID of the project.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name

In

Type

Description

id

body

string

The ID of the network for the auto allocated topology.

tenant_id

body

string

The ID of the project owning the auto allocated topology.

Response Example

{
    "id": "31483d41-5c2b-481c-beef-ab501bd2e0da",
    "tenant_id": "7623217f-dd15-44ec-994a-581a6e41c113"
}
DELETE
/v2.0/auto-allocated-topology/{project_id}

Delete the auto allocated topology

Deletes the auto allocated topology.

Normal response codes: 204

Error response codes: 401, 403, 404

Request

Name

In

Type

Description

project_id

path

string

The ID of the project.

Response

There is no body content for the response of a successful DELETE request.

Tap as a Service

Tap As A Service

TaaS plugin provides a mechanism to mirror certain traffic (for example tagged with specific VLANs) from a source VM to any traffic analyzer VM. When packet will be forwarded, the original value of source and target ip/ports information will not be altered and the system administrator will be able to run, for ex. tcpdump, on the target VM to trace these packets.

TaaS plugin mainly consists of tap service and tap flow.

VLAN filter

The VLAN filtering for Neutron Tap as a Service allows to filter traffic comming from tap-flows by VLAN id in case of mirroring SRIOV ports.

Tap Service

TapService represents the port to which the mirrored traffic is delivered.

GET
/v2.0/taas/tap_services

List Tap Services

List tap services that belong to a given project.

The list might be empty.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request Parameters

Name

In

Type

Description

project (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

project-domain (Optional)

query

string

Domain the project belongs to (name or ID). This can be used in case collisions between project names exist.

Response Parameters

Name

In

Type

Description

id

body

string

Tha id for the Tap Service.

tenant_id

body

string

The ID of the project.

port

body

string

Port to which the Tap service is connected.

status

body

string

Human-readable description of the status for tap service.

Response Example

{
    "tap_services": [
        {
            "id": "257bcb47-5134-4ee9-b5cc-762d99ddae0b",
            "tenant_id": "dad19b09dba44e589c022000d580e9d5",
            "name": "tap_service-1",
            "port_id": "a9855775-48ae-4609-8742-aa9d85db2e01",
            "status": "ACTIVE"
        }
    ]
}
POST
/v2.0/taas/tap_services

Create Tap Service

Create a Tap Service by passing the following JSON-encoded data. name, monitoring port as mandatory parameters and description as optional parameter.

Normal response codes: 201

Error response codes: 401, 403, 404, 409

Request Parameters

Name

In

Type

Description

project (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

project-domain (Optional)

query

string

Domain the project belongs to (name or ID). This can be used in case collisions between project names exist.

tenant_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

name

query

string

The name of the Tap Service.

port (Optional)

query

string

Port to which the Tap service is connected.

description (Optional)

query

string

Filter the list result by the human-readable description of the resource.

Request Example

{
    "tap_service": {
        "name": "ts1",
        "port_id": "a9855775-48ae-4609-8742-aa9d85db2e01"
    }
}

Response Parameters

Name

In

Type

Description

id

body

string

Tha id for the Tap Service.

tenant_id

body

string

The ID of the project.

name

body

string

Tha name for the Tap Flow.

port

body

string

Port to which the Tap service is connected.

status

body

string

Human-readable description of the status for tap service.

description

body

string

The description for this Tap Service.

project_id

body

string

The ID of the project.

Response Example

{
    "tap_service": {
        "id": "2fec9339-f565-46d0-947b-1d98c2a406aa",
        "tenant_id": "dad19b09dba44e589c022000d580e9d5",
        "name": "tap_service-1",
        "description": "tap service",
        "port_id": "a9855775-48ae-4609-8742-aa9d85db2e01",
        "status": "DOWN",
        "project_id": "dad19b09dba44e589c022000d580e9d5"
    }
}
PUT
/v2.0/taas/tap_services/{tap_service_id/name}

Update Tap Service

Update Tap Service by passing tap service name or id as JSON-encoded data. Name or description or both can only be updated.

Normal response codes: 200

Error response codes: 400, 401, 404, 412

Request Parameters

Name

In

Type

Description

name

query

string

The name of the Tap Service.

description (Optional)

query

string

Filter the list result by the human-readable description of the resource.

Request Example

{
    "tap_service": {
        "description": "test tap service"
    }
}

Response Parameters

Name

In

Type

Description

id

body

string

Tha id for the Tap Service.

name

body

string

Tha name for the Tap Flow.

port

body

string

Port to which the Tap service is connected.

status

body

string

Human-readable description of the status for tap service.

description

body

string

The description for this Tap Service.

project_id

body

string

The ID of the project.

Response Example

{
    "tap_service": {
        "id": "2fec9339-f565-46d0-947b-1d98c2a406aa",
        "tenant_id": "dad19b09dba44e589c022000d580e9d5",
        "name": "ts1",
        "description": "test tas",
        "port_id": "a9855775-48ae-4609-8742-aa9d85db2e01",
        "status": "ACTIVE",
        "project_id": "dad19b09dba44e589c022000d580e9d5"
    }
}
DELETE
/v2.0/taas/tap_services/{tap_service_id/name}

Delete Tap Service

Delete Tap Service by passing tap service name or id as JSON-encoded data.

Normal response codes: 204

Error response codes: 400, 401, 404, 412

Request Parameters

Name

In

Type

Description

name

query

string

The name of the Tap Service.

id (Optional)

query

string

The ID of the Tap Service.

Response Parameters

There is no body content for the response of a successful DELETE request.

GET
/v2.0/taas/tap_services/{tap_service_id/name}

Show Tap Service

Show details for a tap service by passing tap service name or id as JSON-encoded data.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request Parameters

Name

In

Type

Description

project (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

project-domain (Optional)

query

string

Domain the project belongs to (name or ID). This can be used in case collisions between project names exist.

name

query

string

The name of the Tap Service.

Response Parameters

Name

In

Type

Description

id

body

string

Tha id for the Tap Service.

name

body

string

Tha name for the Tap Flow.

port

body

string

Port to which the Tap service is connected.

status

body

string

Human-readable description of the status for tap service.

description

body

string

The description for this Tap Service.

project_id

body

string

The ID of the project.

tenant_id

body

string

The ID of the project.

Response Example

{
    "tap_service": {
        "id": "1b059120-078b-4f25-bb16-e14d69706a9a",
        "tenant_id": "dad19b09dba44e589c022000d580e9d5",
        "name": "ts1",
        "description": "",
        "port_id": "a9855775-48ae-4609-8742-aa9d85db2e01",
        "status": "ACTIVE",
        "project_id": "dad19b09dba44e589c022000d580e9d5"
    }
}

Tap Flow

TapFlow represents the port from which the traffic needs to be mirrored. It can be a port associated with VM on another cloud network.

GET
/v2.0/taas/tap_flows

List Tap Flow

List tap flow that belong to a given tenant.

The list might be empty.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request Parameters

Name

In

Type

Description

project (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

project-domain (Optional)

query

string

Domain the project belongs to (name or ID). This can be used in case collisions between project names exist.

Response Parameters

Name

In

Type

Description

id

body

string

The id for the Tap Flow.

port

body

string

Source port to which the Tap Flow is connected.

status

body

string

Human-readable description of the status for tap service.

Response Example

{
    "tap_flows": [
        {
            "ID": "4082b3f6-387f-4d1e-b67e-f47f0dcd2926",
            "Tenant": "dad19b09dba44e589c022000d580e9d5",
            "Name": "tf1",
            "Status": "ACTIVE",
            "source_port": "ee2911c3-08e7-44cb-81aa-fbee2cf43168",
            "tap_service_id": "1b059120-078b-4f25-bb16-e14d69706a9a",
            "Direction": "BOTH"
        }
    ]
}
POST
/v2.0/taas/tap_flows

Create Tap Flow

Create a Tap Flow by passing the following JSON-encoded data. name, source port, direction as IN/OUT/BOTH tap_service as mandatory parameters and description as optional parameter.

Normal response codes: 201

Error response codes: 401, 403, 404, 409

Request Parameters

Name

In

Type

Description

project (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

project-domain (Optional)

query

string

Domain the project belongs to (name or ID). This can be used in case collisions between project names exist.

tenant_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

name

query

string

The name of the Tap flow.

port (Optional)

query

string

Source port to which the Tap Flow is connected.

tap_service (Optional)

query

string

Tap Service to which the Tap Flow belongs.

vlan_filter (Optional)

query

string

VLAN Ids to be mirrored in the form of range string.

direction (Optional)

query

string

Direction of the Tap flow. Possible options are: IN, OUT, BOTH

description (Optional)

query

string

Filter the list result by the human-readable description of the resource.

Request Example

{
    "tap_flow": {
        "name": "tf1",
        "source_port": "ee2911c3-08e7-44cb-81aa-fbee2cf43168",
        "tap_service_id": "1b059120-078b-4f25-bb16-e14d69706a9a",
        "direction": "BOTH"
    }
}

Response Parameters

Name

In

Type

Description

id

body

string

The id for the Tap Flow.

name

body

string

The name for the Tap Flow.

port

body

string

Source port to which the Tap Flow is connected.

status

body

string

Human-readable description of the status for tap flow.

tap_service

body

string

Tap Service to which the Tap Flow belongs.

direction

body

string

The description for this Tap Flow.

project_id

body

string

The ID of the project.

tenant_id

body

string

The ID of the project.

Response Example

{
    "tap_flow": {
        "id": "137086d8-a77b-4bbc-825f-9c2f7b9bfa7b",
        "tenant_id": "dad19b09dba44e589c022000d580e9d5",
        "tap_service_id": "1b059120-078b-4f25-bb16-e14d69706a9a",
        "name": "tf1",
        "description": "",
        "source_port": "ee2911c3-08e7-44cb-81aa-fbee2cf43168",
        "direction": "BOTH",
        "status": "DOWN",
        "vlan_filter": null,
        "project_id": "dad19b09dba44e589c022000d580e9d5"
    }
}
PUT
/v2.0/taas/tap_flows/{taf_service_id/name}

Update Tap Flow

Update Tap Flow by passing tap flow name or id as JSON-encoded data. Name or description or both can only be updated.

Normal response codes: 200

Error response codes: 400, 401, 404, 412

Request Parameters

Name

In

Type

Description

name

query

string

The name of the Tap flow.

description (Optional)

query

string

Filter the list result by the human-readable description of the resource.

Request Example

{
    "tap_flow": {
        "description": "test tap flow"
    }
}

Response Parameters

Name

In

Type

Description

id

body

string

The id for the Tap Flow.

name

body

string

The name for the Tap Flow.

port

body

string

Source port to which the Tap Flow is connected.

status

body

string

Human-readable description of the status for tap service.

tap_service

body

string

Tap Service to which the Tap Flow belongs.

direction

body

string

The description for this Tap Flow.

project_id

body

string

The ID of the project.

tenant_id

body

string

The ID of the project.

Response Example

{
    "tap_flow": {
        "id": "137086d8-a77b-4bbc-825f-9c2f7b9bfa7b",
        "tenant_id": "dad19b09dba44e589c022000d580e9d5",
        "tap_service_id": "1b059120-078b-4f25-bb16-e14d69706a9a",
        "name": "tf1",
        "description": "test tap flow",
        "source_port": "ee2911c3-08e7-44cb-81aa-fbee2cf43168",
        "direction": "BOTH",
        "status": "DOWN",
        "vlan_filter": null,
        "project_id": "dad19b09dba44e589c022000d580e9d5"
    }
}
DELETE
/v2.0/taas/tap_flows/{tap_service_id/name}

Delete Tap Flow

Delete Tap Flow by passing tap flow name or id as JSON-encoded data.

Normal response codes: 204

Error response codes: 400, 401, 404, 412

Request Parameters

Name

In

Type

Description

id (Optional)

query

string

The ID of the Tap flow.

name

query

string

The name of the Tap flow.

Response Parameters

On successful DELETE request Tap flow {tap_flow_id} deleted. message will be displayed.

GET
/v2.0/taas/tap_flows/{tap_flows_id/name}

Show Tap Flow

Show details for a tap flow by passing tap flow name or id as JSON-encoded data.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request Parameters

Name

In

Type

Description

project (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

project-domain (Optional)

query

string

Domain the project belongs to (name or ID). This can be used in case collisions between project names exist.

tenant_id (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

id (Optional)

query

string

The ID of the Tap flow.

name

query

string

The name of the Tap flow.

Response Parameters

Name

In

Type

Description

id

body

string

The id for the Tap Flow.

name

body

string

The name for the Tap Flow.

port

body

string

Source port to which the Tap Flow is connected.

status

body

string

Human-readable description of the status for tap flow.

tap_service

body

string

Tap Service to which the Tap Flow belongs.

direction

body

string

The description for this Tap Flow.

project_id

body

string

The ID of the project.

tenant_id

body

string

The ID of the project.

Response Example

{
    "tap_flow": {
        "id": "137086d8-a77b-4bbc-825f-9c2f7b9bfa7b",
        "tenant_id": "dad19b09dba44e589c022000d580e9d5",
        "tap_service_id": "1b059120-078b-4f25-bb16-e14d69706a9a",
        "name": "tf1",
        "description": "test tap flow",
        "source_port": "ee2911c3-08e7-44cb-81aa-fbee2cf43168",
        "direction": "BOTH",
        "status": "DOWN",
        "vlan_filter": null,
        "project_id": "dad19b09dba44e589c022000d580e9d5"
    }
}

Tap Mirrors

Tap Mirrors provide a way to mirror traffic from a Neutron port to an external IP in a GRE or ERSPAN v1 tunnel.

GET
/v2.0/taas/tap_mirrors

List Tap Mirrors

List tap mirrors that belong to a given project.

The list might be empty.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: 401

Request Parameters

Name

In

Type

Description

project (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

project-domain (Optional)

query

string

Domain the project belongs to (name or ID). This can be used in case collisions between project names exist.

Response Parameters

Name

In

Type

Description

id

body

string

The ID of the Tap Mirror.

name

body

string

The name of the Tap Mirror

description

body

string

A human-readable description for the resource.

tenant_id

body

string

The ID of the project.

port_id

body

string

The Port ID of the Tap Mirror, this will be the source of the mirrored traffic, and this traffic will be tunneled into the GRE or ERSPAN v1 tunnel. The tunnel itself is not starting from this port!

mirror_type

body

string

The type of the mirroring, it can be gre or erspanv1.

remote_ip

body

string

The remote IP of the Tap Mirror, this will be the remote end of the GRE or ERSPAN v1 tunnel.

directions

body

object

A dictionary of direction and tunnel_id. Direction can be IN and OUT.

Response Example

{
    "tap_mirrors": [
        {
            "description": "My fancy tap mirror with direction IN and id 99",
            "directions": {
                "IN": 99
            },
            "id": "207e4809-5358-4592-891b-3312bed32c47",
            "mirror_type": "gre",
            "name": "my_tap_mirror",
            "port_id": "81bc638f-e991-4306-ae5e-df8492890b39",
            "project_id": "57425788f1a148059926c124a6ffabe6",
            "remote_ip": "100.109.0.142",
            "tenant_id": "57425788f1a148059926c124a6ffabe6"
        }
    ]
}
POST
/v2.0/taas/tap_mirrors

Create Tap Mirror

Creates a Tap Mirror.

Error response codes: 401, 403, 404, 409

Request Parameters

Name

In

Type

Description

project (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

project-domain (Optional)

query

string

Domain the project belongs to (name or ID). This can be used in case collisions between project names exist.

tenant_id

body

string

The ID of the project.

name

body

string

The name of the Tap Mirror

port_id

body

string

The Port ID of the Tap Mirror, this will be the source of the mirrored traffic, and this traffic will be tunneled into the GRE or ERSPAN v1 tunnel. The tunnel itself is not starting from this port!

mirror_type

body

string

The type of the mirroring, it can be gre or erspanv1.

remote_ip

body

string

The remote IP of the Tap Mirror, this will be the remote end of the GRE or ERSPAN v1 tunnel.

directions

body

object

A dictionary of direction and tunnel_id. Direction can be IN and OUT.

description

body

string

A human-readable description for the resource.

Request Example

{
    "tap_mirror": {
        "name": "mirror2",
        "description": "Two direction mirror",
        "port_id":"c63e4f48-da76-466c-a6f1-f4e4a4902c6a",
        "directions": {"IN": 99, "OUT": 100},
        "remote_ip":"100.109.0.142",
        "mirror_type":"erspanv1"
    }
}

Response Parameters

Name

In

Type

Description

id

body

string

The ID of the Tap Mirror.

name

body

string

The name of the Tap Mirror

description

body

string

A human-readable description for the resource.

tenant_id

body

string

The ID of the project.

port_id

body

string

The Port ID of the Tap Mirror, this will be the source of the mirrored traffic, and this traffic will be tunneled into the GRE or ERSPAN v1 tunnel. The tunnel itself is not starting from this port!

mirror_type

body

string

The type of the mirroring, it can be gre or erspanv1.

remote_ip

body

string

The remote IP of the Tap Mirror, this will be the remote end of the GRE or ERSPAN v1 tunnel.

directions

body

object

A dictionary of direction and tunnel_id. Direction can be IN and OUT.

Response Example

{
    "tap_mirror": {
        "id": "6ffe758f-d426-4718-9e33-71c542634d2b",
        "project_id": "57425788f1a148059926c124a6ffabe6",
        "name": "mirror2",
        "description": "Two direction mirror",
        "port_id": "c63e4f48-da76-466c-a6f1-f4e4a4902c6a",
        "directions": {"IN": 99, "OUT": 100},
        "remote_ip": "100.109.0.142",
        "mirror_type": "erspanv1",
        "tenant_id": "57425788f1a148059926c124a6ffabe6"
    }
}
PUT
/v2.0/taas/tap_mirrors/{tap_mirror_id}

Update Tap Mirror

Updates Tap Mirror.

Normal response codes: 200

Error response codes: 400, 401, 404, 412

Request Parameters

Name

In

Type

Description

tap_mirror_id

query

string

The id of the Tap Mirror.

description

body

string

A human-readable description for the resource.

name

body

string

The name of the Tap Mirror

Request Example

{
    "tap_mirror": {
        "name": "my_tap_mirror",
        "description":"My fancy tap mirror with direction IN and id 99"
    }
}

Response Parameters

Name

In

Type

Description

id

body

string

The ID of the Tap Mirror.

name

body

string

The name of the Tap Mirror

description

body

string

A human-readable description for the resource.

tenant_id

body

string

The ID of the project.

port_id

body

string

The Port ID of the Tap Mirror, this will be the source of the mirrored traffic, and this traffic will be tunneled into the GRE or ERSPAN v1 tunnel. The tunnel itself is not starting from this port!

mirror_type

body

string

The type of the mirroring, it can be gre or erspanv1.

remote_ip

body

string

The remote IP of the Tap Mirror, this will be the remote end of the GRE or ERSPAN v1 tunnel.

directions

body

object

A dictionary of direction and tunnel_id. Direction can be IN and OUT.

Response Example

{
    "tap_mirror": {
        "id": "207e4809-5358-4592-891b-3312bed32c47",
        "project_id": "57425788f1a148059926c124a6ffabe6",
        "name": "my_tap_mirror",
        "description": "My fancy tap mirror with direction IN and id 99",
        "port_id": "81bc638f-e991-4306-ae5e-df8492890b39",
        "directions": {"IN": 99},
        "remote_ip": "100.109.0.142",
        "mirror_type": "gre",
        "tenant_id": "57425788f1a148059926c124a6ffabe6"
    }
}
DELETE
/v2.0/taas/tap_mirrors/{tap_mirror_id}

Delete Tap Mirror

Deleted a Tap Mirror.

Normal response codes: 204

Error response codes: 400, 401, 404, 412

Request Parameters

Name

In

Type

Description

tap_mirror_id

query

string

The id of the Tap Mirror.

Response Parameters

There is no body content for the response of a successful DELETE request.

GET
/v2.0/taas/tap_mirrors/{tap_mirror_id}

Show Tap Mirror

Shows details for a tap mirror.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: 401, 404

Request Parameters

Name

In

Type

Description

project (Optional)

query

string

Filter the list result by the ID of the project that owns the resource.

project-domain (Optional)

query

string

Domain the project belongs to (name or ID). This can be used in case collisions between project names exist.

tap_mirror_id

query

string

The id of the Tap Mirror.

Response Parameters

Name

In

Type

Description

id

body

string

The ID of the Tap Mirror.

name

body

string

The name of the Tap Mirror

description

body

string

A human-readable description for the resource.

tenant_id

body

string

The ID of the project.

port_id

body

string

The Port ID of the Tap Mirror, this will be the source of the mirrored traffic, and this traffic will be tunneled into the GRE or ERSPAN v1 tunnel. The tunnel itself is not starting from this port!

mirror_type

body

string

The type of the mirroring, it can be gre or erspanv1.

remote_ip

body

string

The remote IP of the Tap Mirror, this will be the remote end of the GRE or ERSPAN v1 tunnel.

directions

body

object

A dictionary of direction and tunnel_id. Direction can be IN and OUT.

Response Example

{
   "tap_mirror" : {
      "description" : "My fancy tap mirror with direction IN and id 99",
      "directions" : {
         "IN" : 99
      },
      "id" : "0f077b67-e85b-4138-bc64-5d705b0a06ef",
      "mirror_type" : "gre",
      "name" : "my_tap_mirror",
      "port_id" : "81bc638f-e991-4306-ae5e-df8492890b39",
      "project_id" : "57425788f1a148059926c124a6ffabe6",
      "remote_ip" : "100.109.0.142",
      "tenant_id" : "57425788f1a148059926c124a6ffabe6"
   }
}

Networking SFC API

Port Chains (port-chains)

Lists, shows information for, creates, updates and deletes port chains.

GET
/v1.0/sfc/port_chains

List Port Chains

Lists port chains.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403)

Response

Name

In

Type

Description

id

body

string

The UUID of the port-chain.

name

body

string

The name of the port-chain.

description

body

string

A human-readable description for the resource.

port_pair_groups

body

array

List of port-pair-group UUIDs.

flow_classifiers (Optional)

body

array

List of flow-classifier UUIDs.

chain_parameters (Optional)

body

object

A dictionary of chain parameters, in the form of correlation: [‘mpls’, ‘nsh’], (default is mpls), weight: integer (defaults to 1).

Response Example

Example List port chains: JSON response

{
    "port_chains": [
        {
            "name": "PC1",
            "id": "1278dcd4-459f-62ed-754b-87fc5e4a6751",
            "tenant_id": "d382007aa9904763a801f68ecf065cf5",
            "description": "Port chain with Firewall and IPS SFs",
            "flow_classifiers": [
                 "4a334cd4-fe9c-4fae-af4b-321c5e2eb051",
                 "105a4b0a-73d6-11e5-b392-2c27d72acb4c"
            ],
            "port_pair_groups": [
                 "4512d643-24fc-4fae-af4b-321c5e2eb3d1",
                 "4a634d49-76dc-4fae-af4b-321c5e23d651"
            ]
        }
    ]
}
POST
/v1.0/sfc/port_chains

Create Port Chain

Creates a port chain.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name

In

Type

Description

name

body

string

The name of the port-chain.

description

body

string

A human-readable description for the resource.

port_pair_groups

body

array

List of port-pair-group UUIDs.

flow_classifiers (Optional)

body

array

List of flow-classifier UUIDs.

chain_parameters (Optional)

body

object

A dictionary of chain parameters, in the form of correlation: [‘mpls’, ‘nsh’], (default is mpls), weight: integer (defaults to 1).

Request Example

Example Create port chain: JSON request

{
    "port_chain": {
        "name": "PC1",
        "tenant_id": "d382007aa9904763a801f68ecf065cf5",
        "description": "Port chain with Firewall and IPS SFs",
        "flow_classifiers": [
             "4a334cd4-fe9c-4fae-af4b-321c5e2eb051",
             "105a4b0a-73d6-11e5-b392-2c27d72acb4c"
        ],
        "port_pair_groups": [
             "4512d643-24fc-4fae-af4b-321c5e2eb3d1",
             "4a634d49-76dc-4fae-af4b-321c5e23d651"
        ]
    }
}

Response

Name

In

Type

Description

id

body

string

The UUID of the port-chain.

name

body

string

The name of the port-chain.

description

body

string

A human-readable description for the resource.

port_pair_groups

body

array

List of port-pair-group UUIDs.

flow_classifiers (Optional)

body

array

List of flow-classifier UUIDs.

chain_parameters (Optional)

body

object

A dictionary of chain parameters, in the form of correlation: [‘mpls’, ‘nsh’], (default is mpls), weight: integer (defaults to 1).

Response Example

Example Create port chain: JSON response

{
    "port_chain": {
        "name": "PC1",
        "tenant_id": "d382007aa9904763a801f68ecf065cf5",
        "description": "Port chain with Firewall and IPS SFs",
        "flow_classifiers": [
             "4a334cd4-fe9c-4fae-af4b-321c5e2eb051",
             "105a4b0a-73d6-11e5-b392-2c27d72acb4c"
        ],
        "port_pair_groups": [
             "4512d643-24fc-4fae-af4b-321c5e2eb3d1",
             "4a634d49-76dc-4fae-af4b-321c5e23d651"
        ],
        "id": "1278dcd4-459f-62ed-754b-87fc5e4a6751"
    }
}
GET
/v1.0/sfc/port_chains/{port_chain_id}

Show Port Chain Details

Shows details for a port chain.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

port_chain_id

path

string

The UUID of the port-chain.

Response

Name

In

Type

Description

id

body

string

The UUID of the port-chain.

name

body

string

The name of the port-chain.

description

body

string

A human-readable description for the resource.

port_pair_groups

body

array

List of port-pair-group UUIDs.

flow_classifiers (Optional)

body

array

List of flow-classifier UUIDs.

chain_parameters (Optional)

body

object

A dictionary of chain parameters, in the form of correlation: [‘mpls’, ‘nsh’], (default is mpls), weight: integer (defaults to 1).

Response Example

Example Show port chain: JSON response

{
    "port_chain": {
        "id": "1278dcd4-459f-62ed-754b-87fc5e4a6751",
        "name": "PC1",
        "tenant_id": "d382007aa9904763a801f68ecf065cf5",
        "description": "Port chain with Firewall and IPS SFs",
        "flow_classifiers": [
             "4a334cd4-fe9c-4fae-af4b-321c5e2eb051",
             "105a4b0a-73d6-11e5-b392-2c27d72acb4c"
        ],
        "port_pair_groups": [
             "4512d643-24fc-4fae-af4b-321c5e2eb3d1",
             "4a634d49-76dc-4fae-af4b-321c5e23d651"
        ]
    }
}
PUT
/v1.0/sfc/port_chains/{port_chain_id}

Update Port Chain

Updates a port chain. The current list of port pair groups is replaced by the port pair group list in the Update request. The current list of flow classifiers is replaced by the flow classifier list in the Update request.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

port_chain_id

path

string

The UUID of the port-chain.

name

body

string

The name of the port-chain.

description

body

string

A human-readable description for the resource.

port_pair_groups

body

array

List of port-pair-group UUIDs.

flow_classifiers (Optional)

body

array

List of flow-classifier UUIDs.

Request Example

Example Update port chain: JSON request

{
    "port_chain": {
        "id": "1278dcd4-459f-62ed-754b-87fc5e4a6751",
        "name": "PC1",
        "tenant_id": "d382007aa9904763a801f68ecf065cf5",
        "description": "Port chain with Firewall and IPS SFs",
        "flow_classifiers": [
             "4a334cd4-fe9c-4fae-af4b-321c5e2eb051",
             "105a4b0a-73d6-11e5-b392-2c27d72acb4c"
        ],
        "port_pair_groups": [
             "4512d643-24fc-4fae-af4b-321c5e2eb3d1",
             "4a634d49-76dc-4fae-af4b-321c5e23d651"
        ]
    }
}

Response

Name

In

Type

Description

id

body

string

The UUID of the port-chain.

name

body

string

The name of the port-chain.

description

body

string

A human-readable description for the resource.

port_pair_groups

body

array

List of port-pair-group UUIDs.

flow_classifiers (Optional)

body

array

List of flow-classifier UUIDs.

Response Example

Example Update port chain: JSON response

{
    "port_chain": {
        "name": "PC1",
        "tenant_id": "d382007aa9904763a801f68ecf065cf5",
        "description": "Port chain with Firewall and IPS SFs",
        "flow_classifiers": [
             "4a334cd4-fe9c-4fae-af4b-321c5e2eb051",
             "105a4b0a-73d6-11e5-b392-2c27d72acb4c"
        ],
        "port_pair_groups": [
             "4512d643-24fc-4fae-af4b-321c5e2eb3d1",
             "4a634d49-76dc-4fae-af4b-321c5e23d651"
        ],
        "id": "1278dcd4-459f-62ed-754b-87fc5e4a6751"
    }
}
DELETE
/v1.0/sfc/port-chains/{port_chain_id}

Delete Port Chain

Deletes a port chain.

Normal response codes: 202

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

port_chain_id

path

string

The UUID of the port-chain.

Response

There is no body content for the response of a successful Delete request.

Port Pair Groups (port-pair-groups)

Lists, shows information for, creates, updates and deletes port pair groups.

GET
/v1.0/sfc/port_pair_groups

List Port Pair Groups

Lists port pair groups.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403)

Response

Name

In

Type

Description

id

body

string

The UUID of the port-pair-group.

name

body

string

The name of the port-pair-group.

description

body

string

A human-readable description for the resource.

port_pairs

body

array

List of port-pair UUIDs.

port_pair_group_parameters (Optional)

body

dict

Dictionary of port pair group parameters, in the form of lb_fields: list of regex (eth|ip|tcp|udp)_(src|dst)), ppg_n_tuple_mapping: ingress_n_tuple or egress_n_tuple. The ingress or egress tuple is a dict with the following keys: source_ip_prefix, destination_ip_prefix, source_port_range_min, source_port_range_max, destination_port_range_min, destination_port_range_max.

tap_enabled (Optional)

body

boolean

True if passive Tap service functions support is enabled, default is False.

Response Example

Example List port pair groups: JSON response

{
    "port_pair_groups": [
        {
             "name": "Firewall_PortPairGroup",
             "tenant_id": "d382007aa9904763a801f68ecf065cf5",
             "description": "Group of Firewall SF instances",
             "port_pairs": [
                 "78dcd363-fc23-aeb6-f44b-56dc5e2fb3ae"
             ],
             "id": "4512d643-24fc-4fae-af4b-321c5e2eb3d1"
        }
    ]
}
POST
/v1.0/sfc/port_pair_groups

Create Port Pair Group

Creates a port pair group.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name

In

Type

Description

name

body

string

The name of the port-pair-group.

description

body

string

A human-readable description for the resource.

port_pairs

body

array

List of port-pair UUIDs.

port_pair_group_parameters (Optional)

body

dict

Dictionary of port pair group parameters, in the form of lb_fields: list of regex (eth|ip|tcp|udp)_(src|dst)), ppg_n_tuple_mapping: ingress_n_tuple or egress_n_tuple. The ingress or egress tuple is a dict with the following keys: source_ip_prefix, destination_ip_prefix, source_port_range_min, source_port_range_max, destination_port_range_min, destination_port_range_max.

tap_enabled (Optional)

body

boolean

True if passive Tap service functions support is enabled, default is False.

Example Create port pair group: JSON request

{
    "port_pair_group": {
         "name": "Firewall_PortPairGroup",
         "tenant_id": "d382007aa9904763a801f68ecf065cf5",
         "description": "Group of Firewall SF instances",
         "port_pairs": [
             "78dcd363-fc23-aeb6-f44b-56dc5e2fb3ae"
         ]
    }
}

Response

Name

In

Type

Description

id

body

string

The UUID of the port-pair-group.

name

body

string

The name of the port-pair-group.

description

body

string

A human-readable description for the resource.

port_pairs

body

array

List of port-pair UUIDs.

port_pair_group_parameters (Optional)

body

dict

Dictionary of port pair group parameters, in the form of lb_fields: list of regex (eth|ip|tcp|udp)_(src|dst)), ppg_n_tuple_mapping: ingress_n_tuple or egress_n_tuple. The ingress or egress tuple is a dict with the following keys: source_ip_prefix, destination_ip_prefix, source_port_range_min, source_port_range_max, destination_port_range_min, destination_port_range_max.

tap_enabled (Optional)

body

boolean

True if passive Tap service functions support is enabled, default is False.

Response Example

Example Create port pair group: JSON response

{
    "port_pair_group": {
         "name": "Firewall_PortPairGroup",
         "tenant_id": "d382007aa9904763a801f68ecf065cf5",
         "description": "Group of Firewall SF instances",
         "port_pairs": [
             "78dcd363-fc23-aeb6-f44b-56dc5e2fb3ae"
         ],
         "id": "4512d643-24fc-4fae-af4b-321c5e2eb3d1"
    }
}
GET
/v1.0/sfc/port_pair_groups/{port_pair_group_id}

Show Port Pair Group Details

Shows details for a port pair group.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

port_pair_group_id

path

string

The UUID of the port-pair-group.

Response

Name

In

Type

Description

id

body

string

The UUID of the port-pair-group.

name

body

string

The name of the port-pair-group.

description

body

string

A human-readable description for the resource.

port_pairs

body

array

List of port-pair UUIDs.

port_pair_group_parameters (Optional)

body

dict

Dictionary of port pair group parameters, in the form of lb_fields: list of regex (eth|ip|tcp|udp)_(src|dst)), ppg_n_tuple_mapping: ingress_n_tuple or egress_n_tuple. The ingress or egress tuple is a dict with the following keys: source_ip_prefix, destination_ip_prefix, source_port_range_min, source_port_range_max, destination_port_range_min, destination_port_range_max.

tap_enabled (Optional)

body

boolean

True if passive Tap service functions support is enabled, default is False.

Response Example

Example Show port pair group: JSON response

{
    "port_pair_group": {
         "name": "Firewall_PortPairGroup",
         "tenant_id": "d382007aa9904763a801f68ecf065cf5",
         "description": "Group of Firewall SF instances",
         "port_pairs": [
             "78dcd363-fc23-aeb6-f44b-56dc5e2fb3ae"
         ],
         "id": "4512d643-24fc-4fae-af4b-321c5e2eb3d1"
    }
}
PUT
/v1.0/sfc/port_pair_groups/{port_pair_group_id}

Update Port Pair Group

Updates a port pair group. The current list of port pairs is replaced by the port pair list in the Update request.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

port_pair_group_id

path

string

The UUID of the port-pair-group.

name

body

string

The name of the port-pair-group.

description

body

string

A human-readable description for the resource.

port_pairs

body

array

List of port-pair UUIDs.

port_pair_group_parameters (Optional)

body

dict

Dictionary of port pair group parameters, in the form of lb_fields: list of regex (eth|ip|tcp|udp)_(src|dst)), ppg_n_tuple_mapping: ingress_n_tuple or egress_n_tuple. The ingress or egress tuple is a dict with the following keys: source_ip_prefix, destination_ip_prefix, source_port_range_min, source_port_range_max, destination_port_range_min, destination_port_range_max.

tap_enabled (Optional)

body

boolean

True if passive Tap service functions support is enabled, default is False.

Request Example

Example Update port pair group: JSON request

{
    "port_pair_group": {
         "name": "Firewall_PortPairGroup",
         "tenant_id": "d382007aa9904763a801f68ecf065cf5",
         "description": "Group of Firewall SF instances",
         "port_pairs": [
             "78dcd363-fc23-aeb6-f44b-56dc5e2fb3ae"
         ]
    }
}

Response

Name

In

Type

Description

id

body

string

The UUID of the port-pair-group.

name

body

string

The name of the port-pair-group.

description

body

string

A human-readable description for the resource.

port_pairs

body

array

List of port-pair UUIDs.

port_pair_group_parameters (Optional)

body

dict

Dictionary of port pair group parameters, in the form of lb_fields: list of regex (eth|ip|tcp|udp)_(src|dst)), ppg_n_tuple_mapping: ingress_n_tuple or egress_n_tuple. The ingress or egress tuple is a dict with the following keys: source_ip_prefix, destination_ip_prefix, source_port_range_min, source_port_range_max, destination_port_range_min, destination_port_range_max.

tap_enabled (Optional)

body

boolean

True if passive Tap service functions support is enabled, default is False.

Response Example

Example Update port pair group: JSON response

{
    "port_pair_group": {
         "name": "Firewall_PortPairGroup",
         "tenant_id": "d382007aa9904763a801f68ecf065cf5",
         "description": "Group of Firewall SF instances",
         "port_pairs": [
             "78dcd363-fc23-aeb6-f44b-56dc5e2fb3ae"
         ],
         "id": "4512d643-24fc-4fae-af4b-321c5e2eb3d1"
    }
}
DELETE
/v1.0/sfc/port-pair-groups/{port_pair_group_id}

Delete Port Pair Group

Deletes a port pair group.

Normal response codes: 202

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

port_pair_group_id

path

string

The UUID of the port-pair-group.

Response

There is no body content for the response of a successful Delete request.

Port Pairs (port-pairs)

Lists, shows information for, creates, updates and deletes port pairs.

GET
/v1.0/sfc/port_pairs

List Port Pairs

Lists port pairs.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403)

Response

Name

In

Type

Description

id

body

string

The UUID of the port-pair.

name

body

string

The name of the port-pair.

description

body

string

A human-readable description for the resource.

port_pair_groups

body

array

List of port-pair-group UUIDs.

flow_classifiers (Optional)

body

array

List of flow-classifier UUIDs.

Response Example

Example List port pairs: JSON response

{
    "port_pairs": [
        {
             "name": "SF1",
             "tenant_id": "d382007aa9904763a801f68ecf065cf5",
             "description": "Firewall SF instance",
             "ingress": "dace4513-24fc-4fae-af4b-321c5e2eb3d1",
             "egress": "aef3478a-4a56-2a6e-cd3a-9dee4e2ec345",
             "id": "78dcd363-fc23-aeb6-f44b-56dc5e2fb3ae"
         }
    ]
}
POST
/v1.0/sfc/port_pairs

Create Port Pair

Creates a port pair.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name

In

Type

Description

name

body

string

The name of the port-pair.

description

body

string

A human-readable description for the resource.

ingress

body

string

The UUID of the ingress Neutron port.

egress

body

string

The UUID of the egress Neutron port.

service_function_parameters (Optional)

body

object

A dictionary of service function parameters, in the form of correlation: mpls or nsh, and weight: integer.

Request Example

Example Create port pair: JSON request

{
    "port_pair": {
         "name": "SF1",
         "tenant_id": "d382007aa9904763a801f68ecf065cf5",
         "description": "Firewall SF instance",
         "ingress": "dace4513-24fc-4fae-af4b-321c5e2eb3d1",
         "egress": "aef3478a-4a56-2a6e-cd3a-9dee4e2ec345"
    }
}

Response

Name

In

Type

Description

id

body

string

The UUID of the port-pair.

name

body

string

The name of the port-pair.

description

body

string

A human-readable description for the resource.

ingress

body

string

The UUID of the ingress Neutron port.

egress

body

string

The UUID of the egress Neutron port.

service_function_parameters (Optional)

body

object

A dictionary of service function parameters, in the form of correlation: mpls or nsh, and weight: integer.

Response Example

Example Create port pair: JSON response

{
    "port_pair": {
         "name": "SF1",
         "tenant_id": "d382007aa9904763a801f68ecf065cf5",
         "description": "Firewall SF instance",
         "ingress": "dace4513-24fc-4fae-af4b-321c5e2eb3d1",
         "egress": "aef3478a-4a56-2a6e-cd3a-9dee4e2ec345",
         "id": "78dcd363-fc23-aeb6-f44b-56dc5e2fb3ae"
     }
}
GET
/v1.0/sfc/port_pairs/{port_pair_id}

Show Port Pair Details

Shows details for a port pair.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

port_pair_id

path

string

The UUID of the port-pair.

Response

Name

In

Type

Description

id

body

string

The UUID of the port-pair.

name

body

string

The name of the port-pair.

description

body

string

A human-readable description for the resource.

ingress

body

string

The UUID of the ingress Neutron port.

egress

body

string

The UUID of the egress Neutron port.

service_function_parameters (Optional)

body

object

A dictionary of service function parameters, in the form of correlation: mpls or nsh, and weight: integer.

Response Example

Example Show port pair: JSON response

{
    "port_pair": {
         "name": "SF1",
         "tenant_id": "d382007aa9904763a801f68ecf065cf5",
         "description": "Firewall SF instance",
         "ingress": "dace4513-24fc-4fae-af4b-321c5e2eb3d1",
         "egress": "aef3478a-4a56-2a6e-cd3a-9dee4e2ec345",
         "id": "78dcd363-fc23-aeb6-f44b-56dc5e2fb3ae"
     }
}
PUT
/v1.0/sfc/port_pairs/{port_pair_id}

Update Port Pair

Updates a port pair.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

port_pair_id

path

string

The UUID of the port-pair.

name

body

string

The name of the port-pair.

description

body

string

A human-readable description for the resource.

Request Example

Example Update port pair: JSON request

{
    "port_pair": {
         "name": "SF1",
         "tenant_id": "d382007aa9904763a801f68ecf065cf5",
         "description": "Firewall SF instance"
    }
}

Response

Name

In

Type

Description

id

body

string

The UUID of the port-pair.

name

body

string

The name of the port-pair.

description

body

string

A human-readable description for the resource.

ingress

body

string

The UUID of the ingress Neutron port.

egress

body

string

The UUID of the egress Neutron port.

service_function_parameters (Optional)

body

object

A dictionary of service function parameters, in the form of correlation: mpls or nsh, and weight: integer.

Response Example

Example Update port pair: JSON response

{
    "port_pair": {
         "name": "SF1",
         "tenant_id": "d382007aa9904763a801f68ecf065cf5",
         "description": "Firewall SF instance",
         "ingress": "dace4513-24fc-4fae-af4b-321c5e2eb3d1",
         "egress": "aef3478a-4a56-2a6e-cd3a-9dee4e2ec345",
         "id": "78dcd363-fc23-aeb6-f44b-56dc5e2fb3ae"
     }
}
DELETE
/v1.0/sfc/port-pairs/{port_pair_id}

Delete Port Pair

Deletes a port pair.

Normal response codes: 202

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

port_pair_id

path

string

The UUID of the port-pair.

Response

There is no body content for the response of a successful Delete request.

Flow Classifiers (flow-classifiers)

Lists, shows information for, creates, updates and deletes flow classifiers.

GET
/v1.0/sfc/flow_classifiers

List Flow Classifiers

Lists flow classifiers.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403)

Response

Name

In

Type

Description

flow_classifier_id

path

string

The ID of the flow classifier.

name

body

string

The name of the flow-classifier.

description

body

string

A human-readable description for the resource.

Response Example

Example List flow classifiers: JSON response

{
     "flow_classifiers": [
        {
             "id": "4a334cd4-fe9c-4fae-af4b-321c5e2eb051",
             "name": "FC1",
             "tenant_id": "1814726e2d22407b8ca76db5e567dcf1",
             "description": "Flow rule for classifying TCP traffic",
             "protocol": "TCP",
             "source_port_range_min": 100,
             "source_port_range_max": 4000,
             "destination_port_range_min": 80,
             "destination_port_range_max": 80,
             "source_ip_prefix": null,
             "destination_ip_prefix": "22.12.34.65"
         }
    ]
}
POST
/v1.0/sfc/flow_classifiers

Create Flow Classifier

Creates a flow classifier.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name

In

Type

Description

name

body

string

The name of the flow-classifier.

description

body

string

A human-readable description for the resource.

ethertype

body

string

Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.

protocol

body

string

The IP protocol can be represented by a string, an integer, or null. Valid string or integer values are any or 0, ah or 51, dccp or 33, egp or 8, esp or 50, gre or 47, icmp or 1, icmpv6 or 58, igmp or 2, ipip or 4, ipv6-encap or 41, ipv6-frag or 44, ipv6-icmp or 58, ipv6-nonxt or 59, ipv6-opts or 60, ipv6-route or 43, ospf or 89, pgm or 113, rsvp or 46, sctp or 132, tcp or 6, udp or 17, udplite or 136, vrrp or 112. Additionally, any integer value between [0-255] is also valid. The string any (or integer 0) means all IP protocols. See the constants in neutron_lib.constants for the most up-to-date list of supported strings.

source_port_range_min (Optional)

body

integer

Minimum source protocol port.

source_port_range_max (Optional)

body

integer

Maximum source protocol port.

destination_port_range_min (Optional)

body

integer

Minimum destination protocol port.

destination_port_range_max (Optional)

body

integer

Maximum destination protocol port.

source_ip_prefix (Optional)

body

string

The source IP prefix.

destination_ip_prefix (Optional)

body

string

The destination IP prefix.

source_logical_port (Optional)

body

string

The UUID of the source logical port.

destination_logical_port (Optional)

body

string

The UUID of the destination logical port.

l7_parameters (Optional)

body

object

A dictionary of L7 parameters, in the form of logical_source_network: uuid, logical_destination_network: uuid.

Request Example

Example Create flow classifier: JSON request

{
     "flow_classifier": {
         "name": "FC1",
         "tenant_id": "1814726e2d22407b8ca76db5e567dcf1",
         "description": "Flow rule for classifying TCP traffic",
         "protocol": "TCP",
         "source_port_range_min": 22,
         "source_port_range_max": 4000,
         "destination_port_range_min": 80,
         "destination_port_range_max": 80,
         "source_ip_prefix": null,
         "destination_ip_prefix": "22.12.34.45"
     }
}

Response

Name

In

Type

Description

flow_classifier_id

path

string

The ID of the flow classifier.

name

body

string

The name of the flow-classifier.

description

body

string

A human-readable description for the resource.

ethertype

body

string

Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.

protocol

body

string

The IP protocol can be represented by a string, an integer, or null. Valid string or integer values are any or 0, ah or 51, dccp or 33, egp or 8, esp or 50, gre or 47, icmp or 1, icmpv6 or 58, igmp or 2, ipip or 4, ipv6-encap or 41, ipv6-frag or 44, ipv6-icmp or 58, ipv6-nonxt or 59, ipv6-opts or 60, ipv6-route or 43, ospf or 89, pgm or 113, rsvp or 46, sctp or 132, tcp or 6, udp or 17, udplite or 136, vrrp or 112. Additionally, any integer value between [0-255] is also valid. The string any (or integer 0) means all IP protocols. See the constants in neutron_lib.constants for the most up-to-date list of supported strings.

source_port_range_min (Optional)

body

integer

Minimum source protocol port.

source_port_range_max (Optional)

body

integer

Maximum source protocol port.

destination_port_range_min (Optional)

body

integer

Minimum destination protocol port.

destination_port_range_max (Optional)

body

integer

Maximum destination protocol port.

source_ip_prefix (Optional)

body

string

The source IP prefix.

destination_ip_prefix (Optional)

body

string

The destination IP prefix.

source_logical_port (Optional)

body

string

The UUID of the source logical port.

destination_logical_port (Optional)

body

string

The UUID of the destination logical port.

l7_parameters (Optional)

body

object

A dictionary of L7 parameters, in the form of logical_source_network: uuid, logical_destination_network: uuid.

Response Example

Example Create flow classifier: JSON response

{
     "flow_classifier": {
         "name": "FC1",
         "tenant_id": "1814726e2d22407b8ca76db5e567dcf1",
         "description": "Flow rule for classifying TCP traffic",
         "protocol": "TCP",
         "source_port_range_min": 22,
         "source_port_range_max": 4000,
         "destination_port_range_min": 80,
         "destination_port_range_max": 80,
         "source_ip_prefix": null,
         "destination_ip_prefix": "22.12.34.45",
         "id": "4a334cd4-fe9c-4fae-af4b-321c5e2eb051"
     }
}
GET
/v1.0/sfc/flow_classifiers/{flow_classifier_id}

Show Flow Classifier Details

Shows details for a flow classifier.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

flow_classifier_id

path

string

The ID of the flow classifier.

Response

Name

In

Type

Description

id

body

string

The UUID of the flow-classifier.

name

body

string

The name of the flow-classifier.

description

body

string

A human-readable description for the resource.

ethertype

body

string

Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.

protocol

body

string

The IP protocol can be represented by a string, an integer, or null. Valid string or integer values are any or 0, ah or 51, dccp or 33, egp or 8, esp or 50, gre or 47, icmp or 1, icmpv6 or 58, igmp or 2, ipip or 4, ipv6-encap or 41, ipv6-frag or 44, ipv6-icmp or 58, ipv6-nonxt or 59, ipv6-opts or 60, ipv6-route or 43, ospf or 89, pgm or 113, rsvp or 46, sctp or 132, tcp or 6, udp or 17, udplite or 136, vrrp or 112. Additionally, any integer value between [0-255] is also valid. The string any (or integer 0) means all IP protocols. See the constants in neutron_lib.constants for the most up-to-date list of supported strings.

source_port_range_min (Optional)

body

integer

Minimum source protocol port.

source_port_range_max (Optional)

body

integer

Maximum source protocol port.

destination_port_range_min (Optional)

body

integer

Minimum destination protocol port.

destination_port_range_max (Optional)

body

integer

Maximum destination protocol port.

source_ip_prefix (Optional)

body

string

The source IP prefix.

destination_ip_prefix (Optional)

body

string

The destination IP prefix.

source_logical_port (Optional)

body

string

The UUID of the source logical port.

destination_logical_port (Optional)

body

string

The UUID of the destination logical port.

l7_parameters (Optional)

body

object

A dictionary of L7 parameters, in the form of logical_source_network: uuid, logical_destination_network: uuid.

Response Example

Example Show flow classifier: JSON response

{
     "flow_classifier": {
         "id": "4a334cd4-fe9c-4fae-af4b-321c5e2eb051",
         "name": "FC1",
         "tenant_id": "1814726e2d22407b8ca76db5e567dcf1",
         "description": "Flow rule for classifying TCP traffic",
         "protocol": "TCP",
         "source_port_range_min": 100,
         "source_port_range_max": 4000,
         "destination_port_range_min": 80,
         "destination_port_range_max": 80,
         "source_ip_prefix": null,
         "destination_ip_prefix": "22.12.34.65"
     }
}
PUT
/v1.0/sfc/flow_classifiers/{flow_classifier_id}

Update Flow Classifier

Updates a flow classifier.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

flow_classifier_id

path

string

The ID of the flow classifier.

name

body

string

The name of the flow-classifier.

description

body

string

A human-readable description for the resource.

Request Example

Example Update flow classifier: JSON request

{
     "flow_classifier": {
         "id": "4a334cd4-fe9c-4fae-af4b-321c5e2eb051",
         "name": "FC1",
         "tenant_id": "1814726e2d22407b8ca76db5e567dcf1",
         "description": "Flow rule for classifying TCP traffic"
     }
}

Response

Name

In

Type

Description

id

body

string

The UUID of the flow-classifier.

name

body

string

The name of the flow-classifier.

description

body

string

A human-readable description for the resource.

ethertype

body

string

Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.

protocol

body

string

The IP protocol can be represented by a string, an integer, or null. Valid string or integer values are any or 0, ah or 51, dccp or 33, egp or 8, esp or 50, gre or 47, icmp or 1, icmpv6 or 58, igmp or 2, ipip or 4, ipv6-encap or 41, ipv6-frag or 44, ipv6-icmp or 58, ipv6-nonxt or 59, ipv6-opts or 60, ipv6-route or 43, ospf or 89, pgm or 113, rsvp or 46, sctp or 132, tcp or 6, udp or 17, udplite or 136, vrrp or 112. Additionally, any integer value between [0-255] is also valid. The string any (or integer 0) means all IP protocols. See the constants in neutron_lib.constants for the most up-to-date list of supported strings.

source_port_range_min (Optional)

body

integer

Minimum source protocol port.

source_port_range_max (Optional)

body

integer

Maximum source protocol port.

destination_port_range_min (Optional)

body

integer

Minimum destination protocol port.

destination_port_range_max (Optional)

body

integer

Maximum destination protocol port.

source_ip_prefix (Optional)

body

string

The source IP prefix.

destination_ip_prefix (Optional)

body

string

The destination IP prefix.

source_logical_port (Optional)

body

string

The UUID of the source logical port.

destination_logical_port (Optional)

body

string

The UUID of the destination logical port.

l7_parameters (Optional)

body

object

A dictionary of L7 parameters, in the form of logical_source_network: uuid, logical_destination_network: uuid.

Response Example

Example Update flow classifier: JSON response

{
     "flow_classifier": {
         "id": "4a334cd4-fe9c-4fae-af4b-321c5e2eb051",
         "name": "FC1",
         "tenant_id": "1814726e2d22407b8ca76db5e567dcf1",
         "description": "Flow rule for classifying TCP traffic",
         "protocol": "TCP",
         "source_port_range_min": 100,
         "source_port_range_max": 4000,
         "destination_port_range_min": 80,
         "destination_port_range_max": 80,
         "source_ip_prefix": null,
         "destination_ip_prefix": "22.12.34.65"
     }
}
DELETE
/v1.0/sfc/flow-classifiers/{flow_classifier_id}

Delete Flow Classifier

Deletes a flow classifier.

Normal response codes: 202

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

flow_classifier_id

path

string

The ID of the flow classifier.

Response

There is no body content for the response of a successful Delete request.

Service Graph (service_graph)

Lists, shows information for, creates, updates and deletes Service Graphs.

GET
/v1.0/sfc/service_graphs

List Service Graphs

Lists service graphs.

Standard query parameters are supported on the URI. For more information, see Filtering and Column Selection.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Pagination query parameters are supported if Neutron configuration supports it by overriding allow_pagination=false. For more information, see Pagination.

Sorting query parameters are supported if Neutron configuration supports it with allow_sorting=true. For more information, see Sorting.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403)

Response

Name

In

Type

Description

id (Optional)

body

boolean

The UUID of the service graph.

name (Optional)

body

boolean

The name of the service graph.

description

body

string

A human-readable description for the resource.

port_chains

body

dict

A dictionary where the key is the source port chain and the value is a list of destination port chains.

Response Example

Example List service graphs: JSON response

{
   "service_graphs":[
      {
         "id":"15e82a5c-c907-4c8c-9501-3e9268178bf8",
         "name":"graph",
         "description":"one graph that uses 6 port chains",
         "tenant_id":"0b18a09b22ef49a5be0bf51d68ed1962",
         "project_id":"0b18a09b22ef49a5be0bf51d68ed1962",
         "port_chains":{
            "19b1965e-f528-4a81-bb05-64b18815fcfc":[
               "3a478b3b-6012-47c6-9c34-6adaffc51b32"
            ],
            "07d0bf74-4293-4e4a-b66f-561ba30bcf76":[
               "3a478b3b-6012-47c6-9c34-6adaffc51b32"
            ],
            "74e01d2b-3dbc-4de8-9969-d4b95d710103":[
               "41e04664-59fb-4f1c-a063-6cfa39ed9ae7",
               "71b514f6-498b-4ae8-ba4e-dff434ad6c1a"
            ],
            "41e04664-59fb-4f1c-a063-6cfa39ed9ae7":[
               "07d0bf74-4293-4e4a-b66f-561ba30bcf76",
               "19b1965e-f528-4a81-bb05-64b18815fcfc"
            ]
         }
      },
      {
         "id":"b91000f0-ece2-4254-9679-76e1ba6843cb",
         "name":"simpler-graph",
         "description":"",
         "tenant_id":"0b18a09b22ef49a5be0bf51d68ed1962",
         "project_id":"0b18a09b22ef49a5be0bf51d68ed1962",
         "port_chains":{
            "ff90b009-396d-4ce7-b387-82a702125e46":[
               "1da89f39-db34-401d-b54b-468e1c648cd1"
            ]
         }
      }
   ]
}
POST
/v1.0/sfc/service_graphs

Create Service Graph

Creates a service graph.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name

In

Type

Description

name (Optional)

body

boolean

The name of the service graph.

description

body

string

A human-readable description for the resource.

port_chains

body

dict

A dictionary where the key is the source port chain and the value is a list of destination port chains.

Example Create service graph: JSON request

{
   "service_graph":{
      "name":"graph",
      "description":"one graph that uses 6 port chains",
      "port_chains":{
         "19b1965e-f528-4a81-bb05-64b18815fcfc":[
            "3a478b3b-6012-47c6-9c34-6adaffc51b32"
         ],
         "07d0bf74-4293-4e4a-b66f-561ba30bcf76":[
            "3a478b3b-6012-47c6-9c34-6adaffc51b32"
         ],
         "41e04664-59fb-4f1c-a063-6cfa39ed9ae7":[
            "07d0bf74-4293-4e4a-b66f-561ba30bcf76",
            "19b1965e-f528-4a81-bb05-64b18815fcfc"
         ],
         "74e01d2b-3dbc-4de8-9969-d4b95d710103":[
            "41e04664-59fb-4f1c-a063-6cfa39ed9ae7",
            "71b514f6-498b-4ae8-ba4e-dff434ad6c1a"
         ]
      }
   }
}

Response

Name

In

Type

Description

id (Optional)

body

boolean

The UUID of the service graph.

name (Optional)

body

boolean

The name of the service graph.

description

body

string

A human-readable description for the resource.

port_chains

body

dict

A dictionary where the key is the source port chain and the value is a list of destination port chains.

Response Example

Example Create service graph: JSON response

{
   "service_graph":{
      "id":"15e82a5c-c907-4c8c-9501-3e9268178bf8",
      "name":"graph",
      "description":"one graph that uses 6 port chains",
      "tenant_id":"0b18a09b22ef49a5be0bf51d68ed1962",
      "project_id":"0b18a09b22ef49a5be0bf51d68ed1962",
      "port_chains":{
         "19b1965e-f528-4a81-bb05-64b18815fcfc":[
            "3a478b3b-6012-47c6-9c34-6adaffc51b32"
         ],
         "07d0bf74-4293-4e4a-b66f-561ba30bcf76":[
            "3a478b3b-6012-47c6-9c34-6adaffc51b32"
         ],
         "74e01d2b-3dbc-4de8-9969-d4b95d710103":[
            "41e04664-59fb-4f1c-a063-6cfa39ed9ae7",
            "71b514f6-498b-4ae8-ba4e-dff434ad6c1a"
         ],
         "41e04664-59fb-4f1c-a063-6cfa39ed9ae7":[
            "07d0bf74-4293-4e4a-b66f-561ba30bcf76",
            "19b1965e-f528-4a81-bb05-64b18815fcfc"
         ]
      }
   }
}
GET
/v1.0/sfc/service_graphs/{sfc_service_graph_id-path}

Show Service Graph Details

Shows details for a service graph.

Use the fields query parameter to control which fields are returned in the response body. For more information, see Fields.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

service_graph_id

path

string

The UUID of the service graph

Response

Name

In

Type

Description

id (Optional)

body

boolean

The UUID of the service graph.

name (Optional)

body

boolean

The name of the service graph.

description

body

string

A human-readable description for the resource.

port_chains

body

dict

A dictionary where the key is the source port chain and the value is a list of destination port chains.

Response Example

Example Show service graph: JSON response

{
   "service_graph":{
      "id":"15e82a5c-c907-4c8c-9501-3e9268178bf8",
      "name":"graph",
      "description":"one graph that uses 6 port chains",
      "tenant_id":"0b18a09b22ef49a5be0bf51d68ed1962",
      "project_id":"0b18a09b22ef49a5be0bf51d68ed1962",
      "port_chains":{
         "19b1965e-f528-4a81-bb05-64b18815fcfc":[
            "3a478b3b-6012-47c6-9c34-6adaffc51b32"
         ],
         "07d0bf74-4293-4e4a-b66f-561ba30bcf76":[
            "3a478b3b-6012-47c6-9c34-6adaffc51b32"
         ],
         "74e01d2b-3dbc-4de8-9969-d4b95d710103":[
            "41e04664-59fb-4f1c-a063-6cfa39ed9ae7",
            "71b514f6-498b-4ae8-ba4e-dff434ad6c1a"
         ],
         "41e04664-59fb-4f1c-a063-6cfa39ed9ae7":[
            "07d0bf74-4293-4e4a-b66f-561ba30bcf76",
            "19b1965e-f528-4a81-bb05-64b18815fcfc"
         ]
      }
   }
}
PUT
/v1.0/sfc/service_graphs/{sfc_service_graph_id-path}

Update Service Graph

Updates a service graph.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

service_graph_id

path

string

The UUID of the service graph

name (Optional)

body

boolean

The name of the service graph.

description

body

string

A human-readable description for the resource.

port_chains

body

dict

A dictionary where the key is the source port chain and the value is a list of destination port chains.

Request Example

Example Update service graph: JSON request

{
   "service_graph":{
      "name":"new-name",
      "description":"and new description, the port_chains dictionary can't be updated"
   }
}

Response

Name

In

Type

Description

id (Optional)

body

boolean

The UUID of the service graph.

name (Optional)

body

boolean

The name of the service graph.

description

body

string

A human-readable description for the resource.

port_chains

body

dict

A dictionary where the key is the source port chain and the value is a list of destination port chains.

Response Example

Example Update service graph: JSON response

{
   "service_graph":{
      "id":"15e82a5c-c907-4c8c-9501-3e9268178bf8",
      "name":"new-name",
      "description":"and new description, the port_chains dictionary can't be updated",
      "tenant_id":"0b18a09b22ef49a5be0bf51d68ed1962",
      "project_id":"0b18a09b22ef49a5be0bf51d68ed1962",
      "port_chains":{
         "19b1965e-f528-4a81-bb05-64b18815fcfc":[
            "3a478b3b-6012-47c6-9c34-6adaffc51b32"
         ],
         "07d0bf74-4293-4e4a-b66f-561ba30bcf76":[
            "3a478b3b-6012-47c6-9c34-6adaffc51b32"
         ],
         "74e01d2b-3dbc-4de8-9969-d4b95d710103":[
            "41e04664-59fb-4f1c-a063-6cfa39ed9ae7",
            "71b514f6-498b-4ae8-ba4e-dff434ad6c1a"
         ],
         "41e04664-59fb-4f1c-a063-6cfa39ed9ae7":[
            "07d0bf74-4293-4e4a-b66f-561ba30bcf76",
            "19b1965e-f528-4a81-bb05-64b18815fcfc"
         ]
      }
   }
}
DELETE
/v1.0/sfc/service_graphs/{sfc_service_graph_id-path}

Delete Service Graph

Deletes a service graph.

Normal response codes: 202

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

service_graph_id

path

string

The UUID of the service graph

Response

There is no body content for the response of a successful Delete request.