Networking API v2.0

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

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/networks?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.

Note

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

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.

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.

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 and shows details for an extension.

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-02-07T10:00:00-00:00",
            "name": "Loadbalancer Agent Scheduler",
            "links": [],
            "alias": "lbaas_agent_scheduler",
            "description": "Schedule pools among lbaas 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": "2012-10-07T10:00:00-00:00",
            "name": "LoadBalancing service",
            "links": [],
            "alias": "lbaas",
            "description": "Extension for LoadBalancing service"
        },
        {
            "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.

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.

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).

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.

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 information, see Filtering and Column Selection.

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.

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

Indicates whether the network has an external routing facility that’s 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.

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.

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

Indicates whether the network has an external routing facility that’s 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.

Use the fields query parameter to control which fields are returned in the response body. Additionally, you can filter results by using query string parameters. For information, see Filtering and Column Selection.

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.

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

Indicates whether the network has an external routing facility that’s 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.

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

Indicates whether the network has an external routing facility that’s 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.

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

Indicates whether the network has an external routing facility that’s 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.

You can control which response parameters are returned by using the fields query parameter. For information, see Filtering and column selection.

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.

Use the fields query parameter to filter the response. For information, see Filtering and Column Selection.

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.

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.

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.

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.

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 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.

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.

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.

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 information, see Filtering and Column Selection.

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.

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 and smart-nic. 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.

name

body

string

Human-readable name of the resource.

network_id

body

string

The ID of the attached network.

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.

revision_number

body

integer

The revision number of the resource.

qos_policy_id

body

string

The ID of the QoS policy associated with the port.

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 a required key for the traits (generated from the vnic_type and the physnet) required by the port, and a resources key for ingress and egress minimum-bandwidth need for the port.

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).

uplink_status_propagation

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": [],
        "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_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae",
        "uplink_status_propagation": false
    }
}

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_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae",
        "resource_request": {
            "required": ["CUSTOM_PHYSNET_PUBLIC", "CUSTOM_VNIC_TYPE_NORMAL"],
            "resources": {"NET_BW_EGR_KILOBIT_PER_SEC": 1000}
        },
        "uplink_status_propagation": false
    }
}
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.

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. The networking API does not define a specific format of this field. The default is an empty dictionary.

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 and smart-nic. 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.

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.

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.

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.

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"
    }
}

Request Example (admin user)

{
    "port": {
        "binding:host_id": "test_for_port_update_host",
        "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.

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 and smart-nic. 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.

name

body

string

Human-readable name of the resource.

network_id

body

string

The ID of the attached network.

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.

revision_number

body

integer

The revision number of the resource.

qos_policy_id

body

string

The ID of the QoS policy associated with the port.

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 a required key for the traits (generated from the vnic_type and the physnet) required by the port, and a resources key for ingress and egress minimum-bandwidth need for the port.

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).

uplink_status_propagation

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": "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_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae",
        "port_security_enabled": false,
        "uplink_status_propagation": false
    }
}

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_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae",
        "port_security_enabled": false,
        "resource_request": {
            "required": ["CUSTOM_PHYSNET_PUBLIC", "CUSTOM_VNIC_TYPE_NORMAL"],
            "resources": {"NET_BW_EGR_KILOBIT_PER_SEC": 1000}
        },
        "uplink_status_propagation": false
    }
}
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.

Use the fields query parameter to control which fields are returned in the response body. Additionally, you can filter results by using query string parameters. For information, see Filtering and Column Selection.

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.

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 and smart-nic. 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.

name

body

string

Human-readable name of the resource.

network_id

body

string

The ID of the attached network.

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.

revision_number

body

integer

The revision number of the resource.

qos_policy_id

body

string

The ID of the QoS policy associated with the port.

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 a required key for the traits (generated from the vnic_type and the physnet) required by the port, and a resources key for ingress and egress minimum-bandwidth need for the port.

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).

uplink_status_propagation

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": 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_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae",
            "port_security_enabled": false,
            "uplink_status_propagation": 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_policy_id": null,
            "port_security_enabled": false,
            "uplink_status_propagation": 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",
            "tenant_id": "",
            "updated_at": "2016-03-08T20:19:41",
            "qos_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae",
            "resource_request": {
                "required": ["CUSTOM_PHYSNET_PUBLIC", "CUSTOM_VNIC_TYPE_NORMAL"],
                "resources": {"NET_BW_EGR_KILOBIT_PER_SEC": 1000}
            },
            "tags": ["tag1,tag2"],
            "tenant_id": "",
            "uplink_status_propagation": false
        },
        {
            "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",
            "tenant_id": "d397de8a63f341818f198abb0966f6f3",
            "updated_at": "2016-03-08T20:19:41",
            "qos_policy_id": null,
            "tags": ["tag1,tag2"],
            "tenant_id": "d397de8a63f341818f198abb0966f6f3",
            "uplink_status_propagation": 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. The networking API does not define a specific format of this field. The default is an empty dictionary.

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 and smart-nic. 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.

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.

uplink_status_propagation (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

{
    "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"
            }
        ],
        "uplink_status_propagation": false
    }
}

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",
        "qos_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae",
        "uplink_status_propagation": false
    }
}

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.

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 and smart-nic. 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.

name

body

string

Human-readable name of the resource.

network_id

body

string

The ID of the attached network.

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.

revision_number

body

integer

The revision number of the resource.

qos_policy_id

body

string

The ID of the QoS policy associated with the port.

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 a required key for the traits (generated from the vnic_type and the physnet) required by the port, and a resources key for ingress and egress minimum-bandwidth need for the port.

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).

uplink_status_propagation

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": "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_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae",
        "uplink_status_propagation": false
    }
}

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"
            }
        ],
        "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_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae",
        "port_security_enabled": true,
        "resource_request": {
            "required": ["CUSTOM_PHYSNET_PUBLIC", "CUSTOM_VNIC_TYPE_NORMAL"],
            "resources": {"NET_BW_EGR_KILOBIT_PER_SEC": 1000}
        },
        "uplink_status_propagation": false
    }
}
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. The networking API does not define a specific format of this field. The default is an empty dictionary.

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 and smart-nic. 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.

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.

uplink_status_propagation (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"
        }
    ]
}

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.

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 and smart-nic. 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.

name

body

string

Human-readable name of the resource.

network_id

body

string

The ID of the attached network.

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.

revision_number

body

integer

The revision number of the resource.

qos_policy_id

body

string

The ID of the QoS policy associated with the port.

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).

uplink_status_propagation

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_policy_id": "29d5e02e-d5ab-4929-bee4-4a9fc12e22ae",
            "port_security_enabled": false,
            "uplink_status_propagation": false
        },
        {
            "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_policy_id": null,
            "port_security_enabled": false,
            "uplink_status_propagation": false
        }
    ]
}

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.

You can control which response parameters are returned by using the fields query parameter. For information, see Filtering and column selection.

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.

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.

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.

Use the fields query parameter to filter the response. For information, see Filtering and Column Selection.

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.

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.

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.

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.

Use the fields query parameter to control which fields are returned in the response body. Additionally, you can filter results by using query string parameters. For information, see the Filtering section for more details.

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

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 information, see Filtering and Column Selection.

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.

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 information, see Filtering and Column Selection.

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.

Use the fields query parameter to control which fields are returned in the response body. Additionally, you can filter results by using query string parameters. For information, see Filtering and Column Selection.

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 information, see Filtering and Column Selection.

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.

Use the fields query parameter to control which fields are returned in the response body. Additionally, you can filter results by using query string parameters. For information, see Filtering and Column Selection.

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 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.

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.

This example request lists floating IPs in JSON format:

GET /v2.0/floatingips
Accept: application/json

Use the fields query parameter to control which fields are returned in the response body. Additionally, you can filter results by using query string parameters. For information, see Filtering and Column Selection.

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.

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.

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.

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 used by internal neutron port (internal_port) and the TCP or UDP port used by floating IP (external_port).

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": []
        },
        {
            "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": []
        },
        {
            "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,
                    "external_port": 2225
                },
                {
                    "protocol": "tcp",
                    "internal_ip_address": "10.0.0.18",
                    "internal_port": 16666,
                    "external_port": 8786
                }
            ]
        }
    ]
}
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.

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.

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.

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"
    }
}

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.

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 used by internal neutron port (internal_port) and the TCP or UDP port used by floating IP (external_port).

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": []
    }
}
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 information, see Filtering and Column Selection.

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.

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 used by internal neutron port (internal_port) and the TCP or UDP port used by floating IP (external_port).

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": []

    }
}
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.

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.

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 used by internal neutron port (internal_port) and the TCP or UDP port used by floating IP (external_port).

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": []
    }
}

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.

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.

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 information, see Filtering and Column Selection.

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

body

integer

The TCP/UDP/other protocol port number of the Neutron port fixed IP address associated to the floating ip port forwarding.

external_port

body

integer

The TCP/UDP/other protocol port number of the port forwarding’s floating IP address.

protocol

body

string

The IP protocol used in the floating IP port forwarding.

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,
    "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.

external_port (Optional)

body

integer

The TCP/UDP/other protocol port number 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
  }
}

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

body

integer

The TCP/UDP/other protocol port number of the Neutron port fixed IP address associated to the floating ip port forwarding.

external_port

body

integer

The TCP/UDP/other protocol port number of the port forwarding’s floating IP address.

protocol

body

string

The IP protocol used in the floating IP port forwarding.

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,
    "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.

Use the fields query parameter to control which fields are returned in the response body. Additionally, you can filter results by using query string parameters. For information, see Filtering and Column Selection.

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.

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

  • 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

body

integer

The TCP/UDP/other protocol port number of the Neutron port fixed IP address associated to the floating ip port forwarding.

external_port

body

integer

The TCP/UDP/other protocol port number of the port forwarding’s floating IP address.

protocol

body

string

The IP protocol used in the floating IP port forwarding.

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,
      "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,
      "id": "e0a0274e-4d19-4eab-9e12-9e77a8caf3ea"
    }
  ]
}
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

body

integer

The TCP/UDP/other protocol port number of the Neutron port fixed IP address associated to the floating ip port forwarding.

external_port

body

integer

The TCP/UDP/other protocol port number of the port forwarding’s floating IP address.

protocol

body

string

The IP protocol used in the floating IP port forwarding.

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
  }
}

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

body

integer

The TCP/UDP/other protocol port number of the Neutron port fixed IP address associated to the floating ip port forwarding.

external_port

body

integer

The TCP/UDP/other protocol port number of the port forwarding’s floating IP address.

protocol

body

string

The IP protocol used in the floating IP port forwarding.

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,
    "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.

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 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 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.

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.

Use the fields query parameter to control which fields are returned in the response body. Additionally, you can filter results by using query string parameters. For information, see Filtering and Column Selection.

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 and external_fixed_ips. 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.

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).

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 and external_fixed_ips. 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.

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 and external_fixed_ips. 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.

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).

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 information, see Filtering and Column Selection.

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 and external_fixed_ips. 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.

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).

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 and external_fixed_ips. 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.

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 and external_fixed_ips. 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.

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).

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"
}

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. Additionally, you can filter results by using query string parameters. For information, see Filtering and Column Selection.

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.

Use the fields query parameter to control which fields are returned in the response body. Additionally, you can filter results by using query string parameters. For information, see Filtering and Column Selection.

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.

Use the fields query parameter to control which fields are returned in the response body. Additionally, you can filter results by using query string parameters. For information, see Filtering and Column Selection.

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.

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"
        },
        {
            "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"
        }
    ]
}
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.

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.

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"
    }
}
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 na