Networking API v2.0

Networking API v2.0

API guide

This section introduces readers to OpenStack Networking (v2) API, providers 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 tenant_id attribute is not required in create requests because the tenant ID is derived from the authentication token.

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

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 both JSON and XML data serialization request and response formats.

Request format

Use the Content-Type request header to specify the request format. This header is required for operations that have a request body.

The syntax for the Content-Type header is:

Content-Type: application/FORMAT

Where FORMAT is either json or xml.

Response format

Use one of the following methods to specify the response format:

Accept header

The syntax for the Accept header is:

Accept: application/FORMAT

Where FORMAT is either json or xml. The default format is json.

Query extension

Add an .xml or .json extension to the request URI. For example, the .xml extension in the following list networks URI request specifies that the response body is to be returned in XML format:

GET publicURL/networks.xml

If you do not specify a response format, JSON is the default.

If the Accept header and the query extension specify conflicting formats, the format specified in the query extension takes precedence. For example, if the query extension is .xml and the Accept header specifies application/json, the response is returned in XML format.

You can serialize a response in a different format from the request format.

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, the Networking API v2.0 returns only objects that meet all filtering criteria. The operation applies an AND condition among the filters.

Note

OpenStack Networking does not offer an OR mechanism for filters.

Alternatively, you can issue a distinct request for each filter and build a response set from the received responses on the client-side.

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.

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

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

Lists available Networking API v2.0 extensions and shows details for an extension.

GET
/v2.0/extensions

List extensions

Lists available extensions.

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

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: 203

Request

Response Parameters

Name In Type Description
updated body string The date and time stamp when the extension was last updated.
description body string The human-readable description for the resource.
links body array The share links.
alias body string The alias for the extension. For example, “FOXNSOX”, “os- availability-zone”, “os-extended-quotas”, “os- share-unmanage” or “os-used-limits.”
extensions body object A list of extension objects.
name body string Human-readable name of 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"
        }
    ]
}
GET
/v2.0/extensions/{alias}

Show extension details

Shows details for an extension, by alias.

Normal response codes: 200

Error response codes: 203

Request

Name In Type Description
alias body string The alias for the extension. For example, “FOXNSOX”, “os- availability-zone”, “os-extended-quotas”, “os- share-unmanage” or “os-used-limits.”

Response Parameters

Name In Type Description
updated body string The date and time stamp when the extension was last updated.
description body string The human-readable description for the resource.
links body array The share links.
alias body string The alias for the extension. For example, “FOXNSOX”, “os- availability-zone”, “os-extended-quotas”, “os- share-unmanage” or “os-used-limits.”
extension body object An extension object.
name body string Human-readable name of the resource.

Response Example

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

Networks

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

GET
/v2.0/networks/{network_id}

Show network details

Shows details for a network.

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

The response might show extension response parameters. For information, see Networks multiple provider extension (networks).

Normal response codes: 200

Error response codes: 404,401

Request

Name In Type Description
network_id body string The UUID of the network.

Response Parameters

Name In Type Description
status body string The network status.
router:external (Optional) body boolean Indicates whether this network is externally accessible.
availability_zone_hints body array The availability zone candidate for the network.
availability_zones body array The availability zone for the network.
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).
tenant_id body string The ID of the tenant who owns the resource.
updated_at body string Time at which port has been updated.
changed_at body string Time at which the network has been created.
mtu body integer The MTU of a network resource.
qos_policy_id (Optional) body string The UUID of the QoS policy.
subnets body array The associated subnets.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
id body string The UUID of the network.
network body object A network object.

Response Example

{
    "network": {
        "status": "ACTIVE",
        "subnets": [
            "54d6f61d-db07-451c-9ab3-b9609b6b6f0b"
        ],
        "name": "private-network",
        "router:external": false,
        "admin_state_up": true,
        "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
        "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e",
        "created_at": "2016-03-08T20:19:41",
        "mtu": 0,
        "shared": true,
        "port_security_enabled": true,
        "updated_at": "2016-03-08T20:19:41",
        "id": "d32019d3-bc6e-4319-9c1d-6722fc136a22"
    }
}
PUT
/v2.0/networks/{network_id}

Update network

Updates a network.

Normal response codes: 200

Error response codes: 404,403,401,400

Request

Name In Type Description
router:external (Optional) body boolean Indicates whether this network is externally accessible.
network body object A network object.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
port_security_enabled (Optional) body boolean The port security status. A valid value is enabled (true) or disabled (false).
name body string Human-readable name of the resource.
network_id body string The UUID of the network.

Request Example

{
    "network": {
        "name": "sample_network_5_updated"
    }
}

Response Parameters

Name In Type Description
status body string The network status.
router:external (Optional) body boolean Indicates whether this network is externally accessible.
availability_zone_hints body array The availability zone candidate for the network.
availability_zones body array The availability zone for the network.
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).
tenant_id body string The ID of the tenant who owns the resource.
mtu body integer The MTU of a network resource.
qos_policy_id (Optional) body string The UUID of the QoS policy.
subnets body array The associated subnets.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
id body string The UUID of the network.
network body object A network object.

Response Example

{
    "network": {
        "status": "ACTIVE",
        "subnets": [],
        "name": "sample_network_5_updated",
        "provider:physical_network": null,
        "admin_state_up": true,
        "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
        "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e",
        "provider:network_type": "local",
        "router:external": false,
        "mtu": 0,
        "shared": false,
        "port_security_enabled": true,
        "id": "1f370095-98f6-4079-be64-6d3d4a6adcc6",
        "provider:segmentation_id": null
    }
}
DELETE
/v2.0/networks/{network_id}

Delete network

Deletes a network and its associated resources.

Error response codes: 409,404,204,401

Request

Name In Type Description
network_id body string The UUID of the network.
GET
/v2.0/networks

List networks

Lists networks to which the tenant has access.

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

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

Response Parameters

Name In Type Description
status body string The network status.
router:external (Optional) body boolean Indicates whether this network is externally accessible.
availability_zone_hints body array The availability zone candidate for the network.
availability_zones body array The availability zone for the network.
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).
tenant_id body string The ID of the tenant who owns the resource.
networks body array A list of network objects.
mtu body integer The MTU of a network resource.
subnets body array The associated subnets.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
id body string The UUID of the network.
qos_policy_id (Optional) body string The UUID of the QoS policy.

Response Example

{
    "networks": [
        {
            "status": "ACTIVE",
            "subnets": [
                "54d6f61d-db07-451c-9ab3-b9609b6b6f0b"
            ],
            "name": "private-network",
            "provider:physical_network": null,
            "admin_state_up": true,
            "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
            "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e",
            "provider:network_type": "local",
            "router:external": true,
            "mtu": 0,
            "shared": true,
            "id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
            "provider:segmentation_id": null
        },
        {
            "status": "ACTIVE",
            "subnets": [
                "08eae331-0402-425a-923c-34f7cfe39c1b"
            ],
            "name": "private",
            "provider:physical_network": null,
            "admin_state_up": true,
            "tenant_id": "26a7980765d0414dbc1fc1f88cdb7e6e",
            "qos_policy_id": "bfdb6c39f71e4d44b1dfbda245c50819",
            "provider:network_type": "local",
            "router:external": true,
            "mtu": 0,
            "shared": true,
            "id": "db193ab3-96e3-4cb3-8fc5-05f4296d0324",
            "provider:segmentation_id": null
        }
    ]
}
POST
/v2.0/networks

Create network

Creates a network.

A request body is optional. An administrative user can specify another tenant UUID, which is the tenant who owns the network, in the request body.

Error response codes: 201,401,400

Request

Request Example

{
    "network": {
        "name": "sample_network",
        "admin_state_up": true
    }
}

Response Parameters

Name In Type Description
status body string The network status.
router:external (Optional) body boolean Indicates whether this network is externally accessible.
availability_zone_hints body array The availability zone candidate for the network.
availability_zones body array The availability zone for the network.
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).
tenant_id body string The ID of the tenant who owns the resource.
mtu body integer The MTU of a network resource.
qos_policy_id (Optional) body string The UUID of the QoS policy.
subnets body array The associated subnets.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
id body string The UUID of the network.
network body object A network object.
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.

Error response codes: 201,401,400

Request

Name In Type Description
router:external (Optional) body boolean Indicates whether this network is externally accessible.
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).
tenant_id body string The ID of the tenant who owns the resource.
port_security_enabled (Optional) body boolean The port security status. A valid value is enabled (true) or disabled (false).
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
networks body array A list of network objects.

Request Example

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

Response Parameters

Name In Type Description
status body string The network status.
router:external (Optional) body boolean Indicates whether this network is externally accessible.
subnets body array The associated subnets.
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).
tenant_id body string The ID of the tenant who owns the resource.
mtu body integer The MTU of a network resource.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
id body string The UUID of the network.
port_security_enabled (Optional) body boolean The port security status. A valid value is enabled (true) or disabled (false).
networks body array A list of network objects.

Networks provider extended attributes (networks)

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

The provider extension decorates network resources with additional attributes. These attributes are provider:network_type, provider:physical_network, and provider:segmentation_id. The validation rules for these attributes are the same as for the Networks multiple provider extension . You cannot use both extensions at the same time.

GET
/v2.0/networks/{network_id}

Show network details (provider network)

Shows details for a network.

Normal response codes: 200

Error response codes: 404,401

Request

Name In Type Description
network_id (Optional) path string The UUID of the network.

Response Parameters

Name In Type Description
status body string The network status.
router:external (Optional) body boolean Indicates whether this network is externally accessible.
availability_zone_hints body array The availability zone candidate for the network.
availability_zones body array The availability zone for the network.
name body string Human-readable name of the resource.
provider:physical_network (Optional) body string The physical network where this network object is 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.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
provider:segmentation_id (Optional) body string An 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.
mtu body integer The MTU of a network resource.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
subnets body array The associated subnets.
port_security_enabled (Optional) body boolean The port security status. A valid value is enabled (true) or disabled (false).
provider:network_type (Optional) body string The type of physical network that maps to this network resource. For example, flat, vlan, vxlan, or gre.
id body string The UUID of the network.
network body object A network object.

Response Example

{
    "network": {
        "status": "ACTIVE",
        "subnets": [
            "54d6f61d-db07-451c-9ab3-b9609b6b6f0b"
        ],
        "name": "private-network",
        "router:external": false,
        "admin_state_up": true,
        "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
        "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e",
        "created_at": "2016-03-08T20:19:41",
        "mtu": 0,
        "shared": true,
        "port_security_enabled": true,
        "updated_at": "2016-03-08T20:19:41",
        "id": "d32019d3-bc6e-4319-9c1d-6722fc136a22"
    }
}
PUT
/v2.0/networks/{network_id}

Update network (provider network)

Updates a network.

Normal response codes: 200

Error response codes: 404,401,400

Request

Name In Type Description
router:external (Optional) body boolean Indicates whether this network is externally accessible.
availability_zone_hints body array The availability zone candidate for the network.
availability_zones body array The availability zone for the network.
network body object A network object.
provider:physical_network (Optional) body string The physical network where this network object is 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.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
provider:network_type (Optional) body string The type of physical network that maps to this network resource. For example, flat, vlan, vxlan, or gre.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
port_security_enabled (Optional) body boolean The port security status. A valid value is enabled (true) or disabled (false).
provider:segmentation_id (Optional) body string An 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.
network_id (Optional) path string The UUID of the network.

Request Example

{
    "network": {
        "name": "sample_network_5_updated"
    }
}

Response Parameters

Name In Type Description
status body string The network status.
router:external (Optional) body boolean Indicates whether this network is externally accessible.
subnets body array The associated subnets.
network body object A network object.
provider:physical_network (Optional) body string The physical network where this network object is 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.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
provider:segmentation_id (Optional) body string An 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.
mtu body integer The MTU of a network resource.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
port_security_enabled (Optional) body boolean The port security status. A valid value is enabled (true) or disabled (false).
provider:network_type (Optional) body string The type of physical network that maps to this network resource. For example, flat, vlan, vxlan, or gre.
id body string The UUID of the network.
name body string Human-readable name of the resource.

Response Example

{
    "network": {
        "status": "ACTIVE",
        "subnets": [],
        "name": "sample_network_5_updated",
        "provider:physical_network": null,
        "admin_state_up": true,
        "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
        "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e",
        "provider:network_type": "local",
        "router:external": false,
        "mtu": 0,
        "shared": false,
        "port_security_enabled": true,
        "id": "1f370095-98f6-4079-be64-6d3d4a6adcc6",
        "provider:segmentation_id": null
    }
}
DELETE
/v2.0/networks/{network_id}

Delete network (provider network)

Deletes a network.

Error response codes: 409,404,204,401

Request

Name In Type Description
network_id (Optional) path string The UUID of the network.
GET
/v2.0/networks

List networks (provider network)

Lists networks that are accessible to the tenant who submits the request.

Normal response codes: 200

Error response codes: 401

Request

Response Parameters

Name In Type Description
status body string The network status.
router:external (Optional) body boolean Indicates whether this network is externally accessible.
availability_zone_hints body array The availability zone candidate for the network.
availability_zones body array The availability zone for the network.
name body string Human-readable name of the resource.
provider:physical_network (Optional) body string The physical network where this network object is 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.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
networks body array A list of network objects.
mtu body integer The MTU of a network resource.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
subnets body array The associated subnets.
port_security_enabled (Optional) body boolean The port security status. A valid value is enabled (true) or disabled (false).
provider:network_type (Optional) body string The type of physical network that maps to this network resource. For example, flat, vlan, vxlan, or gre.
id body string The UUID of the network.
provider:segmentation_id (Optional) body string An 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.

Response Example

{
    "networks": [
        {
            "status": "ACTIVE",
            "subnets": [
                "54d6f61d-db07-451c-9ab3-b9609b6b6f0b"
            ],
            "name": "private-network",
            "provider:physical_network": null,
            "admin_state_up": true,
            "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
            "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e",
            "provider:network_type": "local",
            "router:external": true,
            "mtu": 0,
            "shared": true,
            "id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
            "provider:segmentation_id": null
        },
        {
            "status": "ACTIVE",
            "subnets": [
                "08eae331-0402-425a-923c-34f7cfe39c1b"
            ],
            "name": "private",
            "provider:physical_network": null,
            "admin_state_up": true,
            "tenant_id": "26a7980765d0414dbc1fc1f88cdb7e6e",
            "qos_policy_id": "bfdb6c39f71e4d44b1dfbda245c50819",
            "provider:network_type": "local",
            "router:external": true,
            "mtu": 0,
            "shared": true,
            "id": "db193ab3-96e3-4cb3-8fc5-05f4296d0324",
            "provider:segmentation_id": null
        }
    ]
}
POST
/v2.0/networks

Create network (provider network)

Creates a network.

Error response codes: 201,401,400

Request

Name In Type Description
router:external (Optional) body boolean Indicates whether this network is externally accessible.
network body object A network object.
provider:physical_network (Optional) body string The physical network where this network object is 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.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
provider:network_type (Optional) body string The type of physical network that maps to this network resource. For example, flat, vlan, vxlan, or gre.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
port_security_enabled (Optional) body boolean The port security status. A valid value is enabled (true) or disabled (false).
provider:segmentation_id (Optional) body string An 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.

Request Example

{
    "network": {
        "name": "sample_network",
        "admin_state_up": true
    }
}

Response Parameters

Name In Type Description
status body string The network status.
router:external (Optional) body boolean Indicates whether this network is externally accessible.
availability_zone_hints body array The availability zone candidate for the network.
network body object A network object.
provider:physical_network (Optional) body string The physical network where this network object is 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.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
provider:segmentation_id (Optional) body string An 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.
mtu body integer The MTU of a network resource.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
subnets body array The associated subnets.
port_security_enabled (Optional) body boolean The port security status. A valid value is enabled (true) or disabled (false).
provider:network_type (Optional) body string The type of physical network that maps to this network resource. For example, flat, vlan, vxlan, or gre.
id body string The UUID of the network.
name body string Human-readable name of the resource.

Networks multiple provider extension (networks)

Enables administrative users to define multiple physical bindings for an OpenStack Networking network and list or show details for networks with multiple physical bindings.

You cannot update any provider attributes. If you try to do so, an error occurs.

To delete a network with multiple physical bindings, issue a normal delete network request.

To define multiple physical bindings for a network, include a segments list in the request body of a POST /v2.0/networks 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 validation rules for these attributes are the same as for the Networks provider extended attributes . You cannot use both extensions at the same time.

The NSX and ML2 plug-ins support this extension. With the ML2 plug- in, you can specify multiple VLANs for a network, a VXLAN tunnel ID, and a VLAN.

GET
/v2.0/networks/{network_id}

Show details for a network with multiple segments

Shows details for a network with multiple segments.

Normal response codes: 200

Error response codes: 404,401

Request

Name In Type Description
network_id (Optional) path string The UUID of the network.

Response Parameters

Name In Type Description
status body string The network status.
router:external (Optional) body boolean Indicates whether this network is externally accessible.
subnets body array The associated subnets.
network body object A network object.
provider:physical_network (Optional) body string The physical network where this network object is 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.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
segments body array A list of provider segment objects.
provider:segmentation_id (Optional) body string An 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.
mtu body integer The MTU of a network resource.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
port_security_enabled (Optional) body boolean The port security status. A valid value is enabled (true) or disabled (false).
provider:network_type (Optional) body string The type of physical network that maps to this network resource. For example, flat, vlan, vxlan, or gre.
id body string The UUID of the network.
name body string Human-readable name of the resource.

Response Example

{
    "network": {
        "status": "ACTIVE",
        "subnets": [],
        "name": "net1",
        "admin_state_up": true,
        "tenant_id": "9bacb3c5d39d41a79512987f338cf177",
        "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e",
        "segments": [
            {
                "provider:segmentation_id": 2,
                "provider:physical_network": "8bab8453-1bc9-45af-8c70-f83aa9b50453",
                "provider:network_type": "vlan"
            },
            {
                "provider:segmentation_id": 0,
                "provider:physical_network": "8bab8453-1bc9-45af-8c70-f83aa9b50453",
                "provider:network_type": "stt"
            }
        ],
        "router:external": false,
        "shared": false,
        "id": "4e8e5957-649f-477b-9e5b-f1f75b21c03c"
    }
}
GET
/v2.0/networks

List networks with multiple segment mappings

Lists networks that are accessible to the tenant who submits the request. Networks with multiple segments include the segments list in the response.

Normal response codes: 200

Error response codes: 401

Request

Response Parameters

Name In Type Description
status body string The network status.
router:external (Optional) body boolean Indicates whether this network is externally accessible.
subnets body array The associated subnets.
name body string Human-readable name of the resource.
provider:physical_network (Optional) body string The physical network where this network object is 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.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
segments body array A list of provider segment objects.
mtu body integer The MTU of a network resource.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
id body string The UUID of the network.
port_security_enabled (Optional) body boolean The port security status. A valid value is enabled (true) or disabled (false).
provider:network_type (Optional) body string The type of physical network that maps to this network resource. For example, flat, vlan, vxlan, or gre.
networks body array A list of network objects.
provider:segmentation_id (Optional) body string An 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.

Response Example

{
    "networks": [
        {
            "status": "ACTIVE",
            "subnets": [],
            "name": "net1",
            "admin_state_up": true,
            "tenant_id": "9bacb3c5d39d41a79512987f338cf177",
            "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e",
            "segments": [
                {
                    "provider:segmentation_id": 2,
                    "provider:physical_network": "8bab8453-1bc9-45af-8c70-f83aa9b50453",
                    "provider:network_type": "vlan"
                },
                {
                    "provider:segmentation_id": 0,
                    "provider:physical_network": "8bab8453-1bc9-45af-8c70-f83aa9b50453",
                    "provider:network_type": "stt"
                }
            ],
            "router:external": false,
            "shared": false,
            "id": "4e8e5957-649f-477b-9e5b-f1f75b21c03c"
        },
        {
            "status": "ACTIVE",
            "subnets": [
                "08eae331-0402-425a-923c-34f7cfe39c1b"
            ],
            "name": "private",
            "provider:physical_network": null,
            "router:external": true,
            "admin_state_up": true,
            "tenant_id": "26a7980765d0414dbc1fc1f88cdb7e6e",
            "qos_policy_id": "bfdb6c39f71e4d44b1dfbda245c50819",
            "provider:network_type": "local",
            "shared": true,
            "id": "db193ab3-96e3-4cb3-8fc5-05f4296d0324",
            "provider:segmentation_id": null
        }
    ]
}
POST
/v2.0/networks

Create network with multiple segment mappings

Creates a network with multiple segment mappings.

Error response codes: 201,401,400

Request

Name In Type Description
router:external (Optional) body boolean Indicates whether this network is externally accessible.
network body object A network object.
provider:physical_network (Optional) body string The physical network where this network object is 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.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
segments body array A list of provider segment objects.
provider:network_type (Optional) body string The type of physical network that maps to this network resource. For example, flat, vlan, vxlan, or gre.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
port_security_enabled (Optional) body boolean The port security status. A valid value is enabled (true) or disabled (false).
provider:segmentation_id (Optional) body string An 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.

Request Example

{
    "network": {
        "segments": [
            {
                "provider:segmentation_id": "2",
                "provider:physical_network": "8bab8453-1bc9-45af-8c70-f83aa9b50453",
                "provider:network_type": "vlan"
            },
            {
                "provider:physical_network": "8bab8453-1bc9-45af-8c70-f83aa9b50453",
                "provider:network_type": "stt"
            }
        ],
        "name": "net1",
        "admin_state_up": true
    }
}

Response Parameters

Name In Type Description
status body string The network status.
router:external (Optional) body boolean Indicates whether this network is externally accessible.
subnets body array The associated subnets.
network body object A network object.
provider:physical_network (Optional) body string The physical network where this network object is 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.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
provider:segmentation_id (Optional) body string An 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.
mtu body integer The MTU of a network resource.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
port_security_enabled (Optional) body boolean The port security status. A valid value is enabled (true) or disabled (false).
provider:network_type (Optional) body string The type of physical network that maps to this network resource. For example, flat, vlan, vxlan, or gre.
id body string The UUID of the network.
name body string Human-readable name of the resource.

VLAN transparency extension (networks)

Enables plug-ins that support VLAN transparency to deliver VLAN- transparent trunk networks. 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.

You cannot update the vlan-transparent attribute. If you try to do so, an error occurs.

To delete a VLAN-transparent network, issue a normal delete network request.

The ML2 plug-in currently supports this extension. With the ML2 plug-in, you can set the vlan-transparent attribute to either true or false.

GET
/v2.0/networks/{network_id}

Show VLAN-transparent network details

Shows details for a VLAN-transparent network.

Normal response codes: 200

Error response codes: 404,401

Request

Name In Type Description
network_id (Optional) path string The UUID of the network.

Response Parameters

Name In Type Description
status body string The network status.
router:external (Optional) body boolean Indicates whether this network is externally accessible.
subnets body array The associated subnets.
network body object A network object.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
mtu body integer The MTU of a network resource.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
vlan_transparent body boolean The state of the network, which is VLAN transparent (true) or not VLAN transparent (false).
port_security_enabled (Optional) body boolean The port security status. A valid value is enabled (true) or disabled (false).
id body string The UUID of the network.
name body string Human-readable name of the resource.

Response Example

{
    "network": {
        "status": "ACTIVE",
        "subnets": [],
        "name": "net1",
        "admin_state_up": true,
        "tenant_id": "e926fd5a-e9f6-4dc8-8043-a352d974ceaf",
        "router:external": false,
        "vlan_transparent": true,
        "shared": false,
        "id": "20403fe9-6c9c-48e5-9edb-c3426a955068"
    }
}
GET
/v2.0/networks

List networks with VLAN transparency attribute

Lists networks. The response shows the VLAN transparency attribute.

Normal response codes: 200

Error response codes: 401

Request

Response Parameters

Name In Type Description
status body string The network status.
router:external (Optional) body boolean Indicates whether this network is externally accessible.
subnets body array The associated subnets.
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).
tenant_id body string The ID of the tenant who owns the resource.
mtu body integer The MTU of a network resource.
vlan_transparent body boolean The state of the network, which is VLAN transparent (true) or not VLAN transparent (false).
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
id body string The UUID of the network.
port_security_enabled (Optional) body boolean The port security status. A valid value is enabled (true) or disabled (false).
networks body array A list of network objects.

Response Example

{
    "networks": [
        {
            "status": "ACTIVE",
            "subnets": [],
            "name": "net1",
            "admin_state_up": true,
            "tenant_id": "e252a863-92ee-480f-8bd8-71be77089499",
            "shared": false,
            "router:external": false,
            "vlan_transparent": true,
            "id": "f5e6d63c-04a4-4b2c-8b27-a9854412d5a7"
        },
        {
            "status": "ACTIVE",
            "subnets": [
                "3daba37a-bced-4153-a4bb-d83dcc0552d9"
            ],
            "name": "private",
            "admin_state_up": true,
            "tenant_id": "109e5fae-d976-4791-84c7-6ae0bb3896c3",
            "shared": true,
            "router:external": false,
            "vlan_transparent": false,
            "id": "37e11503-3244-49f1-b92a-9f21bab017d9"
        }
    ]
}
POST
/v2.0/networks

Create VLAN-transparent network

Creates a VLAN-transparent network.

Error response codes: 201,401,400

Request

Name In Type Description
router:external (Optional) body boolean Indicates whether this network is externally accessible.
network body object A network object.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
vlan_transparent body boolean The state of the network, which is VLAN transparent (true) or not VLAN transparent (false).
port_security_enabled (Optional) body boolean The port security status. A valid value is enabled (true) or disabled (false).
name body string Human-readable name of the resource.

Request Example

{
    "network": {
        "name": "net1",
        "admin_state_up": true,
        "vlan_transparent": true
    }
}

Response Parameters

Name In Type Description
status body string The network status.
router:external (Optional) body boolean Indicates whether this network is externally accessible.
subnets body array The associated subnets.
network body object A network object.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
mtu body integer The MTU of a network resource.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
vlan_transparent body boolean The state of the network, which is VLAN transparent (true) or not VLAN transparent (false).
port_security_enabled (Optional) body boolean The port security status. A valid value is enabled (true) or disabled (false).
id body string The UUID of the network.
name body string Human-readable name of the resource.

Subnets

Lists, shows details for, creates, updates, and deletes subnet resources.

GET
/v2.0/subnets

List subnets

Lists subnets to which the tenant has access.

Default policy settings returns exclusively subnets owned by the tenant submitting the request, unless the request is submitted by a user with administrative rights. You can control which attributes are returned by using the fields query parameter. You can filter results by using query string parameters.

Normal response codes: 200

Error response codes: 401

Request

Response Example

{
    "subnets": [
        {
            "name": "private-subnet",
            "enable_dhcp": true,
            "network_id": "db193ab3-96e3-4cb3-8fc5-05f4296d0324",
            "tenant_id": "26a7980765d0414dbc1fc1f88cdb7e6e",
            "dns_nameservers": [],
            "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"
        },
        {
            "name": "my_subnet",
            "enable_dhcp": true,
            "network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
            "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
            "dns_nameservers": [],
            "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"
        }
    ]
}
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.

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

Request

Request Example

{
    "subnet": {
        "network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
        "ip_version": 4,
        "cidr": "10.0.0.1"
    }
}
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.

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

Request

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"
        }
    ]
}
GET
/v2.0/subnets/{subnet_id}

Show subnet details

Shows details for a subnet.

Use the fields query parameter to filter the results.

Normal response codes: 200

Error response codes: 404,401

Request

Name In Type Description
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.

Response Example

{
    "subnet": {
        "name": "my_subnet",
        "enable_dhcp": true,
        "network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
        "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
        "created_at": "2016-03-08T20:19:41",
        "dns_nameservers": [],
        "allocation_pools": [
            {
                "start": "192.0.0.2",
                "end": "192.255.255.254"
            }
        ],
        "host_routes": [],
        "ip_version": 4,
        "gateway_ip": "192.0.0.1",
        "cidr": "192.0.0.0/8",
        "updated_at": "2016-03-08T20:19:41",
        "id": "54d6f61d-db07-451c-9ab3-b9609b6b6f0b"
    }
}
PUT
/v2.0/subnets/{subnet_id}

Update subnet

Updates a subnet.

Some attributes, such as IP version (ip_version), and CIDR (cidr) cannot be updated. Attempting to update these attributes results in a 400 Bad Request error.

Normal response codes: 200

Error response codes: 404,403,401,400

Request

Name In Type Description
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.

Request Example

{
    "subnet": {
        "name": "my_subnet"
    }
}

Response Example

{
    "subnet": {
        "name": "my_subnet",
        "enable_dhcp": true,
        "network_id": "db193ab3-96e3-4cb3-8fc5-05f4296d0324",
        "tenant_id": "26a7980765d0414dbc1fc1f88cdb7e6e",
        "dns_nameservers": [],
        "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"
    }
}
DELETE
/v2.0/subnets/{subnet_id}

Delete subnet

Deletes a subnet.

The operation fails if subnet IP addresses are still allocated.

Error response codes: 409,404,204,401

Request

Name In Type Description
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.

Ports

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

GET
/v2.0/ports/{port_id}

Show port details

Shows details for a port.

Normal response codes: 200

Error response codes: 404,401

Request

Name In Type Description
port_id (Optional) path string The UUID of the port.

Response Parameters

Name In Type Description
opt_value (Optional) body string The extra DHCP option value.
status body string The network status.
name body string Human-readable name of the resource.
allowed_address_pairs (Optional) body array A set of zero or more allowed address pairs. An address pair contains an IP address and MAC address.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
network_id body string The UUID of the network.
ip_address (Optional) body string The IP address of an allowed address pair.
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.
opt_name (Optional) body string The extra DHCP option name.
updated_at body string Time at which port has been updated.
id body string The UUID of the network.
port body object A port object.
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
device_owner (Optional) body string The UUID of the entity that uses this port. For example, a DHCP agent.
tenant_id body string The ID of the tenant who owns the resource.
mac_address (Optional) body string The MAC address of an allowed address pair.
port_security_enabled (Optional) body boolean The port security status. A valid value is enabled (true) or disabled (false).
fixed_ips (Optional) body array If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
created_at body string Time at which port has been created.
security_groups (Optional) body array One or more security group UUIDs.
device_id (Optional) body string The UUID of the device that uses this port. For example, a virtual server.

Response Example

{
    "port": {
        "status": "ACTIVE",
        "name": "",
        "allowed_address_pairs": [],
        "admin_state_up": true,
        "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7",
        "tenant_id": "7e02058126cc4950b75f9970368ba177",
        "created_at": "2016-03-08T20:19:41",
        "extra_dhcp_opts": [],
        "device_owner": "network:router_interface",
        "mac_address": "fa:16:3e:23:fd:d7",
        "fixed_ips": [
            {
                "subnet_id": "a0304c3a-4f08-4c43-88af-d796509c97d2",
                "ip_address": "10.0.0.1"
            }
        ],
        "id": "46d4bfb9-b26e-41f3-bd2e-e6dcc1ccedb2",
        "updated_at": "2016-03-08T20:19:41",
        "security_groups": [],
        "device_id": "5e3898d7-11be-483e-9732-b2f5eccd2b2e"
    }
}
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.

Normal response codes: 200

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

Request

Name In Type Description
opt_value (Optional) body string The extra DHCP option value.
name body string Human-readable name of the resource.
allowed_address_pairs (Optional) body array A set of zero or more allowed address pairs. An address pair contains an IP address and MAC address.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
network_id body string The UUID of the network.
fixed_ips (Optional) body array If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
opt_name (Optional) body string The extra DHCP option name.
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
device_owner (Optional) body string The UUID of the entity that uses this port. For example, a DHCP agent.
tenant_id body string The ID of the tenant who owns the resource.
mac_address (Optional) body string The MAC address of an allowed address pair.
ip_address (Optional) body string The IP address of an allowed address pair.
port body object A port object.
security_groups (Optional) body array One or more security group UUIDs.
device_id (Optional) body string The UUID of the device that uses this port. For example, a virtual server.
port_id (Optional) path string The UUID of the port.

Request Example

{
    "port": {
        "name": "test-for-port-update",
        "admin_state_up": true,
        "device_owner": "compute:nova",
        "binding:host_id": "test_for_port_update_host"
    }
}

Response Parameters

Name In Type Description
opt_value (Optional) body string The extra DHCP option value.
status body string The network status.
name body string Human-readable name of the resource.
allowed_address_pairs (Optional) body array A set of zero or more allowed address pairs. An address pair contains an IP address and MAC address.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
network_id body string The UUID of the network.
ip_address (Optional) body string The IP address of an allowed address pair.
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.
opt_name (Optional) body string The extra DHCP option name.
updated_at body string Time at which port has been updated.
id body string The UUID of the network.
port body object A port object.
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
device_owner (Optional) body string The UUID of the entity that uses this port. For example, a DHCP agent.
tenant_id body string The ID of the tenant who owns the resource.
mac_address (Optional) body string The MAC address of an allowed address pair.
port_security_enabled (Optional) body boolean The port security status. A valid value is enabled (true) or disabled (false).
fixed_ips (Optional) body array If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
created_at body string Time at which port has been created.
security_groups (Optional) body array One or more security group UUIDs.
device_id (Optional) body string The UUID of the device that uses this port. For example, a virtual server.

Response Example

{
    "port": {
        "status": "DOWN",
        "binding:host_id": "test_for_port_update_host",
        "allowed_address_pairs": [],
        "extra_dhcp_opts": [],
        "device_owner": "compute:nova",
        "binding:profile": {},
        "fixed_ips": [
            {
                "subnet_id": "898dec4a-74df-4193-985f-c76721bcc746",
                "ip_address": "20.20.0.4"
            }
        ],
        "id": "43c831e0-19ce-4a76-9a49-57b57e69428b",
        "security_groups": [
            "ce0179d6-8a94-4f7c-91c2-f3038e2acbd0"
        ],
        "device_id": "",
        "name": "test-for-port-update",
        "admin_state_up": true,
        "network_id": "883fc383-5ea1-4c8b-8916-e1ddb0a9f365",
        "tenant_id": "522eda8d23124b25bf03fe44f1986b74",
        "binding:vif_details": {},
        "binding:vnic_type": "normal",
        "binding:vif_type": "binding_failed",
        "mac_address": "fa:16:3e:11:11:5e"
    }
}
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.

Error response codes: 404,403,204,401

Request

Name In Type Description
port_id (Optional) path string The UUID of the port.
GET
/v2.0/ports

List ports

Lists ports to which the tenant has access.

Default policy settings return only those ports that are owned by the tenant who submits the request, unless the request is submitted by a user with administrative rights. Users can control which attributes are returned by using the fields query parameter. You can use query parameters to filter the response.For information, see Filtering and Column Selection.

Normal response codes: 200

Error response codes: 401

Request

Response Parameters

Name In Type Description
opt_value (Optional) body string The extra DHCP option value.
status body string The network status.
name body string Human-readable name of the resource.
allowed_address_pairs (Optional) body array A set of zero or more allowed address pairs. An address pair contains an IP address and MAC address.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
network_id body string The UUID of the network.
ip_address (Optional) body string The IP address of an allowed address pair.
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.
opt_name (Optional) body string The extra DHCP option name.
updated_at body string Time at which port has been updated.
id body string The UUID of the network.
ports body array A list of port objects.
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
device_owner (Optional) body string The UUID of the entity that uses this port. For example, a DHCP agent.
tenant_id body string The ID of the tenant who owns the resource.
mac_address (Optional) body string The MAC address of an allowed address pair.
port_security_enabled (Optional) body boolean The port security status. A valid value is enabled (true) or disabled (false).
fixed_ips (Optional) body array If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
created_at body string Time at which port has been created.
security_groups (Optional) body array One or more security group UUIDs.
device_id (Optional) body string The UUID of the device that uses this port. For example, a virtual server.

Response Example

{
    "ports": [
        {
            "status": "ACTIVE",
            "name": "",
            "allowed_address_pairs": [],
            "admin_state_up": true,
            "network_id": "70c1db1f-b701-45bd-96e0-a313ee3430b3",
            "tenant_id": "",
            "extra_dhcp_opts": [],
            "device_owner": "network:router_gateway",
            "mac_address": "fa:16:3e:58:42:ed",
            "fixed_ips": [
                {
                    "subnet_id": "008ba151-0b8c-4a67-98b5-0d2b87666062",
                    "ip_address": "172.24.4.2"
                }
            ],
            "id": "d80b1a3b-4fc1-49f3-952e-1e2ab7081d8b",
            "security_groups": [],
            "device_id": "9ae135f4-b6e0-4dad-9e91-3c223e385824"
        },
        {
            "status": "ACTIVE",
            "name": "",
            "allowed_address_pairs": [],
            "admin_state_up": true,
            "network_id": "f27aa545-cbdd-4907-b0c6-c9e8b039dcc2",
            "tenant_id": "d397de8a63f341818f198abb0966f6f3",
            "extra_dhcp_opts": [],
            "device_owner": "network:router_interface",
            "mac_address": "fa:16:3e:bb:3c:e4",
            "fixed_ips": [
                {
                    "subnet_id": "288bf4a1-51ba-43b6-9d0a-520e9005db17",
                    "ip_address": "10.0.0.1"
                }
            ],
            "id": "f71a6703-d6de-4be1-a91a-a570ede1d159",
            "security_groups": [],
            "device_id": "9ae135f4-b6e0-4dad-9e91-3c223e385824"
        }
    ]
}
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.

Error response codes: 201,404,403,401,400,503

Request

Name In Type Description
opt_value (Optional) body string The extra DHCP option value.
name body string Human-readable name of the resource.
allowed_address_pairs (Optional) body array A set of zero or more allowed address pairs. An address pair contains an IP address and MAC address.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
network_id body string The UUID of the network.
fixed_ips (Optional) body array If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
opt_name (Optional) body string The extra DHCP option name.
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
device_owner (Optional) body string The UUID of the entity that uses this port. For example, a DHCP agent.
tenant_id body string The ID of the tenant who owns the resource.
mac_address (Optional) body string The MAC address of an allowed address pair.
ip_address (Optional) body string The IP address of an allowed address pair.
port body object A port object.
security_groups (Optional) body array One or more security group UUIDs.
device_id (Optional) body string The UUID of the device that uses this port. For example, a virtual server.

Request Example

{
    "port": {
        "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7",
        "name": "private-port",
        "admin_state_up": true
    }
}

Response Parameters

Name In Type Description
opt_value (Optional) body string The extra DHCP option value.
status body string The network status.
name body string Human-readable name of the resource.
allowed_address_pairs (Optional) body array A set of zero or more allowed address pairs. An address pair contains an IP address and MAC address.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
network_id body string The UUID of the network.
ip_address (Optional) body string The IP address of an allowed address pair.
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.
opt_name (Optional) body string The extra DHCP option name.
updated_at body string Time at which port has been updated.
id body string The UUID of the network.
port body object A port object.
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
device_owner (Optional) body string The UUID of the entity that uses this port. For example, a DHCP agent.
tenant_id body string The ID of the tenant who owns the resource.
mac_address (Optional) body string The MAC address of an allowed address pair.
port_security_enabled (Optional) body boolean The port security status. A valid value is enabled (true) or disabled (false).
fixed_ips (Optional) body array If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
created_at body string Time at which port has been created.
security_groups (Optional) body array One or more security group UUIDs.
device_id (Optional) body string The UUID of the device that uses this port. For example, a virtual server.
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.

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

Request

Name In Type Description
opt_value (Optional) body string The extra DHCP option value.
name body string Human-readable name of the resource.
allowed_address_pairs (Optional) body array A set of zero or more allowed address pairs. An address pair contains an IP address and MAC address.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
network_id body string The UUID of the network.
fixed_ips (Optional) body array If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
opt_name (Optional) body string The extra DHCP option name.
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
device_owner (Optional) body string The UUID of the entity that uses this port. For example, a DHCP agent.
tenant_id body string The ID of the tenant who owns the resource.
mac_address (Optional) body string The MAC address of an allowed address pair.
ip_address (Optional) body string The IP address of an allowed address pair.
ports body array A list of port objects.
security_groups (Optional) body array One or more security group UUIDs.
device_id (Optional) body string The UUID of the device that uses this port. For example, a virtual server.

Request Example

{
    "ports": [
        {
            "name": "sample_port_1",
            "admin_state_up": false,
            "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7"
        },
        {
            "name": "sample_port_2",
            "admin_state_up": false,
            "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7"
        }
    ]
}

Response Parameters

Name In Type Description
opt_value (Optional) body string The extra DHCP option value.
status body string The network status.
name body string Human-readable name of the resource.
allowed_address_pairs (Optional) body array A set of zero or more allowed address pairs. An address pair contains an IP address and MAC address.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
network_id body string The UUID of the network.
ip_address (Optional) body string The IP address of an allowed address pair.
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.
opt_name (Optional) body string The extra DHCP option name.
updated_at body string Time at which port has been updated.
id body string The UUID of the network.
ports body array A list of port objects.
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
device_owner (Optional) body string The UUID of the entity that uses this port. For example, a DHCP agent.
tenant_id body string The ID of the tenant who owns the resource.
mac_address (Optional) body string The MAC address of an allowed address pair.
port_security_enabled (Optional) body boolean The port security status. A valid value is enabled (true) or disabled (false).
fixed_ips (Optional) body array If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
created_at body string Time at which port has been created.
security_groups (Optional) body array One or more security group UUIDs.
device_id (Optional) body string The UUID of the device that uses this port. For example, a virtual server.

Ports binding extended attributes (ports)

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

GET
/v2.0/ports/{port_id}

Show port details (port binding)

Shows details for a port.

Normal response codes: 200

Request

Name In Type Description
port_id (Optional) path string The UUID of the port.

Response Example

{
    "port": {
        "status": "ACTIVE",
        "binding:host_id": "devstack",
        "name": "",
        "allowed_address_pairs": [],
        "admin_state_up": true,
        "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7",
        "tenant_id": "7e02058126cc4950b75f9970368ba177",
        "extra_dhcp_opts": [],
        "binding:vif_details": {
            "port_filter": true,
            "ovs_hybrid_plug": true
        },
        "binding:vif_type": "ovs",
        "device_owner": "network:router_interface",
        "port_security_enabled": false,
        "mac_address": "fa:16:3e:23:fd:d7",
        "binding:profile": {},
        "binding:vnic_type": "normal",
        "fixed_ips": [
            {
                "subnet_id": "a0304c3a-4f08-4c43-88af-d796509c97d2",
                "ip_address": "10.0.0.1"
            }
        ],
        "id": "46d4bfb9-b26e-41f3-bd2e-e6dcc1ccedb2",
        "security_groups": [],
        "device_id": "5e3898d7-11be-483e-9732-b2f5eccd2b2e"
    }
}
PUT
/v2.0/ports/{port_id}

Update port (port binding)

Updates a port.

Normal response codes: 200

Error response codes: 404,401,400

Request

Name In Type Description
port_id (Optional) path string The UUID of the port.

Request Example

{
    "port": {
        "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7",
        "name": "private-port",
        "admin_state_up": true
    }
}

Response Example

{
    "port": {
        "status": "DOWN",
        "binding:host_id": "",
        "name": "private-port",
        "allowed_address_pairs": [],
        "admin_state_up": true,
        "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7",
        "tenant_id": "d6700c0c9ffa4f1cb322cd4a1f3906fa",
        "binding:vif_details": {},
        "binding:vnic_type": "normal",
        "binding:vif_type": "unbound",
        "device_owner": "",
        "mac_address": "fa:16:3e:c9:cb:f0",
        "binding:profile": {},
        "fixed_ips": [
            {
                "subnet_id": "a0304c3a-4f08-4c43-88af-d796509c97d2",
                "ip_address": "10.0.0.2"
            }
        ],
        "id": "65c0ee9f-d634-4522-8954-51021b570b0d",
        "security_groups": [
            "f0ac4394-7e4a-4409-9701-ba8be283dbc3"
        ],
        "device_id": ""
    }
}
DELETE
/v2.0/ports/{port_id}

Delete port (port binding)

Deletes a port.

Error response codes: 409,404,204,401

Request

Name In Type Description
port_id (Optional) path string The UUID of the port.
GET
/v2.0/ports

List ports (port binding)

Lists ports to which the tenant has access.

Normal response codes: 200

Error response codes: 401

Request

Response Example

{
    "ports": [
        {
            "status": "ACTIVE",
            "name": "",
            "allowed_address_pairs": [],
            "admin_state_up": true,
            "network_id": "70c1db1f-b701-45bd-96e0-a313ee3430b3",
            "tenant_id": "",
            "extra_dhcp_opts": [],
            "device_owner": "network:router_gateway",
            "mac_address": "fa:16:3e:58:42:ed",
            "fixed_ips": [
                {
                    "subnet_id": "008ba151-0b8c-4a67-98b5-0d2b87666062",
                    "ip_address": "172.24.4.2"
                }
            ],
            "id": "d80b1a3b-4fc1-49f3-952e-1e2ab7081d8b",
            "security_groups": [],
            "device_id": "9ae135f4-b6e0-4dad-9e91-3c223e385824"
        },
        {
            "status": "ACTIVE",
            "name": "",
            "allowed_address_pairs": [],
            "admin_state_up": true,
            "network_id": "f27aa545-cbdd-4907-b0c6-c9e8b039dcc2",
            "tenant_id": "d397de8a63f341818f198abb0966f6f3",
            "extra_dhcp_opts": [],
            "device_owner": "network:router_interface",
            "mac_address": "fa:16:3e:bb:3c:e4",
            "fixed_ips": [
                {
                    "subnet_id": "288bf4a1-51ba-43b6-9d0a-520e9005db17",
                    "ip_address": "10.0.0.1"
                }
            ],
            "id": "f71a6703-d6de-4be1-a91a-a570ede1d159",
            "security_groups": [],
            "device_id": "9ae135f4-b6e0-4dad-9e91-3c223e385824"
        }
    ]
}
POST
/v2.0/ports

Create port (port binding)

Creates a port on a network.

Error response codes: 201,403,401,400

Request

Request Example

{
    "port": {
        "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7",
        "name": "private-port",
        "admin_state_up": true
    }
}

Subnet pools extension (subnetpools)

Lists, creates, shows details for, updates, and deletes subnet pools.

GET
/v2.0/subnetpools/{subnetpool_id}

Show subnet pool

Shows information for a subnet pool.

Use the fields query parameter to filter the results.

Normal response codes: 200

Error response codes: 404,401

Request

Name In Type Description
subnetpool_id (Optional) path string The UUID of the subnet pool.

Response Parameters

Name In Type Description
name body string Human-readable name of the resource.
default_quota (Optional) body integer A per-tenant quota on the prefix space that can be allocated from the subnet pool for tenant 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 tenants that use the subnet pool have the same prefix quota applied.
tenant_id body string The ID of the tenant who owns the resource.
created_at body string Time at which port has been created.
subnetpool body object A subnetpool object.
updated_at body string Time at which port has been updated.
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 string 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 Admin-only. Indicates whether this network is shared across all tenants.
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.
id body string The UUID of the network.
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.

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,
        "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
    }
}
PUT
/v2.0/subnetpools/{subnetpool_id}

Update subnet pool

Updates a subnet pool.

Normal response codes: 200

Error response codes: 404,403,401,400

Request

Name In Type Description
name body string Human-readable name of the resource.
default_quota (Optional) body integer A per-tenant quota on the prefix space that can be allocated from the subnet pool for tenant 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 tenants that use the subnet pool have the same prefix quota applied.
tenant_id body string The ID of the tenant who owns the resource.
subnetpool body object A subnetpool object.
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 string 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.
subnetpool_id (Optional) path string The UUID of the subnet pool.

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
name body string Human-readable name of the resource.
default_quota (Optional) body integer A per-tenant quota on the prefix space that can be allocated from the subnet pool for tenant 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 tenants that use the subnet pool have the same prefix quota applied.
tenant_id body string The ID of the tenant who owns the resource.
created_at body string Time at which port has been created.
subnetpool body object A subnetpool object.
updated_at body string Time at which port has been updated.
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 string 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 Admin-only. Indicates whether this network is shared across all tenants.
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.
id body string The UUID of the network.
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.

Response Example

{
    "subnetpool": {
        "name": "my-new-subnetpool-name",
        "default_quota": null,
        "is_default": false,
        "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
    }
}
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.

Error response codes: 404,204,401

Request

Name In Type Description
subnetpool_id (Optional) path string The UUID of the subnet pool.
GET
/v2.0/subnetpools

List subnet pools

Lists subnet pools to which the tenant has access.

Default policy settings returns exclusively subnet pools owned by the tenant submitting the request, unless the request is submitted by a user with administrative rights.

Normal response codes: 200

Error response codes: 401

Request

Response Parameters

Name In Type Description
name body string Human-readable name of the resource.
default_quota (Optional) body integer A per-tenant quota on the prefix space that can be allocated from the subnet pool for tenant 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 tenants that use the subnet pool have the same prefix quota applied.
tenant_id body string The ID of the tenant who owns the resource.
created_at body string Time at which port has been created.
updated_at body string Time at which port has been updated.
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 string 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 Admin-only. Indicates whether this network is shared across all tenants.
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.
subnetpools body array A list of subnetpool objects.
id body string The UUID of the network.
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.

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,
            "tenant_id": "9fadcee8aa7c40cdb2114fff7d569c08",
            "prefixes": [
                "2001:db8:0:2::/64",
                "2001:db8::/63"
            ],
            "ip_version": 6,
            "shared": false
        },
        {
            "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,
            "tenant_id": "9fadcee8aa7c40cdb2114fff7d569c08",
            "prefixes": [
                "10.10.0.0/21",
                "192.168.0.0/16"
            ],
            "ip_version": 4,
            "shared": false
        }
    ]
}
POST
/v2.0/subnetpools

Create subnet pool

Creates a subnet pool.

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

Request

Name In Type Description
name body string Human-readable name of the resource.
default_quota (Optional) body integer A per-tenant quota on the prefix space that can be allocated from the subnet pool for tenant 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 tenants that use the subnet pool have the same prefix quota applied.
tenant_id body string The ID of the tenant who owns the resource.
subnetpool body object A subnetpool object.
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 string An address scope to assign to the subnet pool.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
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.

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
name body string Human-readable name of the resource.
default_quota (Optional) body integer A per-tenant quota on the prefix space that can be allocated from the subnet pool for tenant 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 tenants that use the subnet pool have the same prefix quota applied.
tenant_id body string The ID of the tenant who owns the resource.
created_at body string Time at which port has been created.
subnetpool body object A subnetpool object.
updated_at body string Time at which port has been updated.
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 string 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 Admin-only. Indicates whether this network is shared across all tenants.
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.
id body string The UUID of the network.
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.

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.

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
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 tenant who owns the resource.
name body string Human-readable name of the resource.
description body string The 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.
network_id body string Network ID which the router gateway is connected to.
enable_snat body boolean Enable Source NAT (SNAT) attribute. true means Network Address Translation (NAT) is enabled for traffic generated by subnets attached to the router when the traffic is sent to/received from the external network. false means no NAT is applied for traffic from/to the external network. It is available when ext-gw-mode extension is enabled.
external_fixed_ips body array IP address(es) of the external gateway of the router. It is a list of IP addresses. Each element of the list is a dictionary of ip_address and subnet_id.
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.

Response Example

{
    "routers": [
        {
            "admin_state_up": true,
            "availability_zone_hints": [],
            "availability_zones": [
                "nova"
            ],
            "description": "",
            "distributed": false,
            "external_gateway_info": {
                "enable_snat": true,
                "external_fixed_ips": [
                    {
                        "ip_address": "172.24.4.3",
                        "subnet_id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf"
                    },
                    {
                        "ip_address": "2001:db8::c",
                        "subnet_id": "0c56df5d-ace5-46c8-8f4c-45fa4e334d18"
                    }
                ],
                "network_id": "ae34051f-aa6c-4c75-abf5-50dc9ac99ef3"
            },
            "ha": false,
            "id": "915a14a6-867b-4af7-83d1-70efceb146f9",
            "name": "router2",
            "routes": [],
            "status": "ACTIVE",
            "tenant_id": "0bd18306d801447bb457a46252d82d13"
        },
        {
            "admin_state_up": true,
            "availability_zone_hints": [],
            "availability_zones": [
                "nova"
            ],
            "description": "",
            "distributed": false,
            "external_gateway_info": {
                "enable_snat": true,
                "external_fixed_ips": [
                    {
                        "ip_address": "172.24.4.6",
                        "subnet_id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf"
                    },
                    {
                        "ip_address": "2001:db8::9",
                        "subnet_id": "0c56df5d-ace5-46c8-8f4c-45fa4e334d18"
                    }
                ],
                "network_id": "ae34051f-aa6c-4c75-abf5-50dc9ac99ef3"
            },
            "ha": false,
            "id": "f8a44de0-fc8e-45df-93c7-f79bf3b01c95",
            "name": "router1",
            "routes": [],
            "status": "ACTIVE",
            "tenant_id": "0bd18306d801447bb457a46252d82d13"
        }
    ]
}
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 tenant who owns the resource. Only administrative users can specify a tenant UUID 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 The human-readable description for the resource.
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.
network_id body string Network ID which the router gateway is connected to.
enable_snat (Optional) body boolean Enable Source NAT (SNAT) attribute. Default is true. To persist this attribute value, set the enable_snat_by_default option in the neutron.conf file. It is available when ext-gw-mode extension is enabled.
external_fixed_ips (Optional) body array IP address(es) of the external gateway interface of the router. It is a list of IP addresses you would like to assign to the external gateway interface. Each element of ths list is a dictionary of ip_address and subnet_id.
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.

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 tenant who owns the resource.
name body string Human-readable name of the resource.
description body string The 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.
network_id body string Network ID which the router gateway is connected to.
enable_snat body boolean Enable Source NAT (SNAT) attribute. true means Network Address Translation (NAT) is enabled for traffic generated by subnets attached to the router when the traffic is sent to/received from the external network. false means no NAT is applied for traffic from/to the external network. It is available when ext-gw-mode extension is enabled.
external_fixed_ips body array IP address(es) of the external gateway of the router. It is a list of IP addresses. Each element of the list is a dictionary of ip_address and subnet_id.
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.

Response Example

{
    "router": {
        "admin_state_up": true,
        "availability_zone_hints": [],
        "availability_zones": [
            "nova"
        ],
        "description": "",
        "distributed": false,
        "external_gateway_info": {
            "enable_snat": true,
            "external_fixed_ips": [
                {
                    "ip_address": "172.24.4.6",
                    "subnet_id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf"
                }
            ],
            "network_id": "ae34051f-aa6c-4c75-abf5-50dc9ac99ef3"
        },
        "ha": false,
        "id": "f8a44de0-fc8e-45df-93c7-f79bf3b01c95",
        "name": "router1",
        "routes": [],
        "status": "ACTIVE",
        "tenant_id": "0bd18306d801447bb457a46252d82d13"
    }
}
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 tenant who owns the resource.
name body string Human-readable name of the resource.
description body string The 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.
network_id body string Network ID which the router gateway is connected to.
enable_snat body boolean Enable Source NAT (SNAT) attribute. true means Network Address Translation (NAT) is enabled for traffic generated by subnets attached to the router when the traffic is sent to/received from the external network. false means no NAT is applied for traffic from/to the external network. It is available when ext-gw-mode extension is enabled.
external_fixed_ips body array IP address(es) of the external gateway of the router. It is a list of IP addresses. Each element of the list is a dictionary of ip_address and subnet_id.
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.

Response Example

{
    "router": {
        "admin_state_up": true,
        "availability_zone_hints": [],
        "availability_zones": [
            "nova"
        ],
        "description": "",
        "distributed": false,
        "external_gateway_info": {
            "enable_snat": true,
            "external_fixed_ips": [
                {
                    "ip_address": "172.24.4.6",
                    "subnet_id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf"
                },
                {
                    "ip_address": "2001:db8::9",
                    "subnet_id": "0c56df5d-ace5-46c8-8f4c-45fa4e334d18"
                }
            ],
            "network_id": "ae34051f-aa6c-4c75-abf5-50dc9ac99ef3"
        },
        "ha": false,
        "id": "f8a44de0-fc8e-45df-93c7-f79bf3b01c95",
        "name": "router1",
        "routes": [],
        "status": "ACTIVE",
        "tenant_id": "0bd18306d801447bb457a46252d82d13"
    }
}
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 intreface, use the add router interface and remove router interface operations.

Normal response codes: 200

Error response codes: 400, 401, 404

Request

Name In Type Description
router body object A router object.
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.
enable_snat body boolean Enable Source NAT (SNAT) attribute. true means Network Address Translation (NAT) is enabled for traffic generated by subnets attached to the router when the traffic is sent to/received from the external network. false means no NAT is applied for traffic from/to the external network. It is available when ext-gw-mode 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).
external_fixed_ips body array IP address(es) of the external gateway of the router. It is a list of IP addresses. Each element of the list is a dictionary of ip_address and subnet_id.
router_id path string The ID of the router.

Request Example

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

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 tenant who owns the resource.
name body string Human-readable name of the resource.
description body string The 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.
network_id body string Network ID which the router gateway is connected to.
enable_snat body boolean Enable Source NAT (SNAT) attribute. true means Network Address Translation (NAT) is enabled for traffic generated by subnets attached to the router when the traffic is sent to/received from the external network. false means no NAT is applied for traffic from/to the external network. It is available when ext-gw-mode extension is enabled.
external_fixed_ips body array IP address(es) of the external gateway of the router. It is a list of IP addresses. Each element of the list is a dictionary of ip_address and subnet_id.
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.

Response Example

{
    "router": {
        "admin_state_up": true,
        "availability_zone_hints": [],
        "availability_zones": [
            "nova"
        ],
        "description": "",
        "distributed": false,
        "external_gateway_info": {
            "enable_snat": true,
            "external_fixed_ips": [
                {
                    "ip_address": "172.24.4.6",
                    "subnet_id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf"
                }
            ],
            "network_id": "ae34051f-aa6c-4c75-abf5-50dc9ac99ef3"
        },
        "ha": false,
        "id": "f8a44de0-fc8e-45df-93c7-f79bf3b01c95",
        "name": "router1",
        "routes": [],
        "status": "ACTIVE",
        "tenant_id": "0bd18306d801447bb457a46252d82d13"
    }
}
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

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

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"
    ],
    "tenant_id": "0bd18306d801447bb457a46252d82d13"
}
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 tenant 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.

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"
    ],
    "tenant_id": "0bd18306d801447bb457a46252d82d13"
}

Floating IPs (floatingips)

GET
/v2.0/floatingips

List floating IPs

Lists floating IPs that are accessible to the tenant who submits the request.

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

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

Response Parameters

Name In Type Description
router_id path string The ID of the router.
status body string The network status.
tenant_id body string The ID of the tenant who owns the resource.
floating_network_id body string The UUID 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. To associate the floating IP with a fixed IP at creation time, you must specify the identifier of the internal port. 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) path string The UUID of the port.
id body string The UUID of the network.
floatingips body array A list of floatingip objects.

Response Example

{
    "floatingips": [
        {
            "router_id": "d23abc8d-2991-4a55-ba98-2aaea84cc72f",
            "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"
        },
        {
            "router_id": null,
            "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"
        }
    ]
}
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 UUID attribute in the request body. If you do not specify a port UUID 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 UUID 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.

Error codes:

  • 400 The operation returns this error code for one of these 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.
  • 401 The operation is not authorized.
  • 404 The port UUID is not valid.
  • 409 The operation returns this error code for one of these 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.

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

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 tenant who owns the resource.
floating_network_id body string The UUID 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. To associate the floating IP with a fixed IP at creation time, you must specify the identifier of the internal port. 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) path string The UUID of the port.

Request Example

{
    "floatingip": {
        "floating_network_id": "376da547-b977-4cfe-9cba-275c80debf57",
        "port_id": "ce705c24-c1ef-408a-bda3-7bbd946164ab"
    }
}

Response Parameters

Name In Type Description
router_id path string The ID of the router.
status body string The network status.
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 tenant who owns the resource.
floating_network_id body string The UUID 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. To associate the floating IP with a fixed IP at creation time, you must specify the identifier of the internal port. 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) path string The UUID of the port.
id body string The UUID of the network.
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:404,403,401,

Request

Name In Type Description
floatingip_id (Optional) path string The UUID of the floating IP address.

Response Parameters

Name In Type Description
router_id path string The ID of the router.
status body string The network status.
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 tenant who owns the resource.
floating_network_id body string The UUID 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. To associate the floating IP with a fixed IP at creation time, you must specify the identifier of the internal port. 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) path string The UUID of the port.
id body string The UUID of the network.

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",
        "tenant_id": "4969c491a3c74ee4af974e6d800c62de",
        "status": "ACTIVE",
        "port_id": "ce705c24-c1ef-408a-bda3-7bbd946164ab",
        "id": "2f245a7b-796b-4f26-9cf9-9e82d248fda7"
    }
}
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:404,409,401,400,

Request

Name In Type Description
port_id (Optional) path string The UUID of the port.
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 (Optional) path string The UUID of the floating IP address.

Request Example

{
    "floatingip": {
        "port_id": null
    }
}

Response Parameters

Name In Type Description
router_id path string The ID of the router.
status body string The network status.
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 tenant who owns the resource.
floating_network_id body string The UUID 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. To associate the floating IP with a fixed IP at creation time, you must specify the identifier of the internal port. 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) path string The UUID of the port.
id body string The UUID of the network.

Response Example

{
    "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",
        "tenant_id": "4969c491a3c74ee4af974e6d800c62de",
        "status": "ACTIVE",
        "port_id": null,
        "id": "2f245a7b-796b-4f26-9cf9-9e82d248fda7"
    }
}
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

Error response codes:404,204,401,

Request

Name In Type Description
floatingip_id (Optional) path string The UUID of the floating IP address.

Security groups (security-groups)

Lists, creates, shows information for, updates, and deletes security groups.

GET
/v2.0/security-groups/{security_group_id}

Show security group

Shows details for a security group.

The response contains the description, name, UUID, and security group rules that are associated with the security group and tenant.

Normal response codes: 200

Error response codes: 404,401

Request

Name In Type Description
security_group_id body string The security group UUID to associate with this security group rule.
verbose (Optional) query boolean Show detailed information.
fields (Optional) query string The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

Response Parameters

Name In Type Description
remote_group_id (Optional) body string The remote group UUID to associate with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body.
direction body string Ingress or egress, which is the direction in which the metering rule is applied.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
description body string The human-readable description for the resource.
ethertype (Optional) body string Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.
port_range_max (Optional) body integer The maximum port number in the range that is matched by the security group rule. The port_range_min attribute constrains the port_range_max attribute. If the protocol is ICMP, this value must be an ICMP type.
security_group_rules body array A list of security_group_rule objects.
security_group_id body string The security group UUID to associate with this security group rule.
tenant_id body string The ID of the tenant who owns the resource.
port_range_min (Optional) body integer The minimum port number in the range that is matched by the security group rule. If the protocol is TCP or UDP, this value must be less than or equal to the port_range_max attribute value. If the protocol is ICMP, this value must be an ICMP type.
remote_ip_prefix body string The remote IP prefix to associate with this metering rule packet.
security_group body object A security_group object.
id body string The UUID of the network.
name body string Human-readable name of the resource.

Response Example

{
    "security_group": {
        "description": "default",
        "id": "85cc3048-abc3-43cc-89b3-377341426ac5",
        "name": "default",
        "security_group_rules": [
            {
                "direction": "egress",
                "ethertype": "IPv6",
                "id": "3c0e45ff-adaf-4124-b083-bf390e5482ff",
                "port_range_max": null,
                "port_range_min": null,
                "protocol": null,
                "remote_group_id": null,
                "remote_ip_prefix": null,
                "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
                "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550"
            },
            {
                "direction": "egress",
                "ethertype": "IPv4",
                "id": "93aa42e5-80db-4581-9391-3a608bd0e448",
                "port_range_max": null,
                "port_range_min": null,
                "protocol": null,
                "remote_group_id": null,
                "remote_ip_prefix": null,
                "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
                "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550"
            },
            {
                "direction": "ingress",
                "ethertype": "IPv6",
                "id": "c0b09f00-1d49-4e64-a0a7-8a186d928138",
                "port_range_max": null,
                "port_range_min": null,
                "protocol": null,
                "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
                "remote_ip_prefix": null,
                "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
                "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550"
            },
            {
                "direction": "ingress",
                "ethertype": "IPv4",
                "id": "f7d45c89-008e-4bab-88ad-d6811724c51c",
                "port_range_max": null,
                "port_range_min": null,
                "protocol": null,
                "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
                "remote_ip_prefix": null,
                "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
                "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550"
            }
        ],
        "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550"
    }
}
PUT
/v2.0/security-groups/{security_group_id}

Update security group

Updates a security group.

Normal response codes: 200

Error response codes: 413,405,404,403,401,400,503

Request

Name In Type Description
description body string The human-readable description for the resource.
name body string Human-readable name of the resource.
security_group_id body string The security group UUID to associate with this security group rule.

Request Example

{
    "security_group": {
        "name": "mysecgroup",
        "description": "my security group"
    }
}

Response Parameters

Name In Type Description
security_group body object A security_group object.
tenant_id body string The ID of the tenant who owns the resource.
description body string The human-readable description for the resource.
name body string Human-readable name of the resource.
id body string The UUID of the network.

Response Example

{
    "security_group": {
        "rules": [],
        "tenant_id": "a52cdb9cc7854a39a23d3af73a40899e",
        "id": "01fbade5-b664-42f6-83ae-4e214f4263fa",
        "name": "mysecgroup",
        "description": "my security group"
    }
}
DELETE
/v2.0/security-groups/{security_group_id}

Delete security group

Deletes an OpenStack Networking security group.

This operation deletes an OpenStack Networking security group and its associated security group rules, provided that a port is not associated with the security group.

This operation does not require a request body. This operation does not return a response body.

Error response codes: 409,404,204,401

Request

Name In Type Description
security_group_id body string The security group UUID to associate with this security group rule.
GET
/v2.0/security-groups

List security groups

Lists OpenStack Networking security groups to which the tenant has access.

The list shows the UUID for and the rules that are associated with each security group.

Normal response codes: 200

Error response codes: 401

Request

Response Parameters

Name In Type Description
remote_group_id (Optional) body string The remote group UUID to associate with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body.
direction body string Ingress or egress, which is the direction in which the metering rule is applied.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
description body string The human-readable description for the resource.
ethertype (Optional) body string Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.
port_range_max (Optional) body integer The maximum port number in the range that is matched by the security group rule. The port_range_min attribute constrains the port_range_max attribute. If the protocol is ICMP, this value must be an ICMP type.
security_group_rules body array A list of security_group_rule objects.
security_group_id body string The security group UUID to associate with this security group rule.
tenant_id body string The ID of the tenant who owns the resource.
port_range_min (Optional) body integer The minimum port number in the range that is matched by the security group rule. If the protocol is TCP or UDP, this value must be less than or equal to the port_range_max attribute value. If the protocol is ICMP, this value must be an ICMP type.
remote_ip_prefix body string The remote IP prefix to associate with this metering rule packet.
id body string The UUID of the network.
security_groups (Optional) body array One or more security group UUIDs.
name body string Human-readable name of the resource.

Response Example

{
    "security_groups": [
        {
            "description": "default",
            "id": "85cc3048-abc3-43cc-89b3-377341426ac5",
            "name": "default",
            "security_group_rules": [
                {
                    "direction": "egress",
                    "ethertype": "IPv6",
                    "id": "3c0e45ff-adaf-4124-b083-bf390e5482ff",
                    "port_range_max": null,
                    "port_range_min": null,
                    "protocol": null,
                    "remote_group_id": null,
                    "remote_ip_prefix": null,
                    "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
                    "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550"
                },
                {
                    "direction": "egress",
                    "ethertype": "IPv4",
                    "id": "93aa42e5-80db-4581-9391-3a608bd0e448",
                    "port_range_max": null,
                    "port_range_min": null,
                    "protocol": null,
                    "remote_group_id": null,
                    "remote_ip_prefix": null,
                    "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
                    "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550"
                },
                {
                    "direction": "ingress",
                    "ethertype": "IPv6",
                    "id": "c0b09f00-1d49-4e64-a0a7-8a186d928138",
                    "port_range_max": null,
                    "port_range_min": null,
                    "protocol": null,
                    "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
                    "remote_ip_prefix": null,
                    "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
                    "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550"
                },
                {
                    "direction": "ingress",
                    "ethertype": "IPv4",
                    "id": "f7d45c89-008e-4bab-88ad-d6811724c51c",
                    "port_range_max": null,
                    "port_range_min": null,
                    "protocol": null,
                    "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
                    "remote_ip_prefix": null,
                    "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
                    "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550"
                }
            ],
            "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550"
        }
    ]
}
POST
/v2.0/security-groups

Create security group

Creates an OpenStack Networking security group.

This operation creates a security group with default security group rules for the IPv4 and IPv6 ether types.

Error response codes: 201,401,400

Request

Name In Type Description
security_group body object A security_group object.
tenant_id body string The ID of the tenant who owns the resource.
description body string The human-readable description for the resource.
name body string Human-readable name of the resource.

Request Example

{
    "security_group": {
        "name": "new-webservers",
        "description": "security group for webservers"
    }
}

Response Parameters

Name In Type Description
remote_group_id (Optional) body string The remote group UUID to associate with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body.
direction body string Ingress or egress, which is the direction in which the metering rule is applied.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
description body string The human-readable description for the resource.
ethertype (Optional) body string Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.
port_range_max (Optional) body integer The maximum port number in the range that is matched by the security group rule. The port_range_min attribute constrains the port_range_max attribute. If the protocol is ICMP, this value must be an ICMP type.
security_group_rules body array A list of security_group_rule objects.
security_group_id body string The security group UUID to associate with this security group rule.
tenant_id body string The ID of the tenant who owns the resource.
port_range_min (Optional) body integer The minimum port number in the range that is matched by the security group rule. If the protocol is TCP or UDP, this value must be less than or equal to the port_range_max attribute value. If the protocol is ICMP, this value must be an ICMP type.
remote_ip_prefix body string The remote IP prefix to associate with this metering rule packet.
security_group body object A security_group object.
id body string The UUID of the network.
name body string Human-readable name of the resource.

Security group rules (security-group-rules)

Lists, creates, shows information for, and deletes security group rules.

GET
/v2.0/security-group-rules/{security-group-rules-id}

Show security group rule

Shows detailed information for a security group rule.

The response body contains the following information about the security group rule:

Normal response codes: 200

Error response codes: 404,401

Request

Response Parameters

Name In Type Description
remote_group_id (Optional) body string The remote group UUID to associate with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body.
direction body string Ingress or egress, which is the direction in which the metering rule is applied.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
ethertype (Optional) body string Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.
port_range_max (Optional) body integer The maximum port number in the range that is matched by the security group rule. The port_range_min attribute constrains the port_range_max attribute. If the protocol is ICMP, this value must be an ICMP type.
security_group_id body string The security group UUID to associate with this security group rule.
security_group_rule body object A security_group_rule object.
tenant_id body string The ID of the tenant who owns the resource.
port_range_min (Optional) body integer The minimum port number in the range that is matched by the security group rule. If the protocol is TCP or UDP, this value must be less than or equal to the port_range_max attribute value. If the protocol is ICMP, this value must be an ICMP type.
remote_ip_prefix body string The remote IP prefix to associate with this metering rule packet.
id body string The UUID of the network.

Response Example

{
    "security_group_rule": {
        "direction": "egress",
        "ethertype": "IPv6",
        "id": "3c0e45ff-adaf-4124-b083-bf390e5482ff",
        "port_range_max": null,
        "port_range_min": null,
        "protocol": null,
        "remote_group_id": null,
        "remote_ip_prefix": null,
        "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
        "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550"
    }
}
DELETE
/v2.0/security-group-rules/{security-group-rules-id}

Delete security group rule

Deletes a rule from an OpenStack Networking security group.

Error response codes: 404,204,401

Request

GET
/v2.0/security-group-rules

List security group rules

Lists a summary of all OpenStack Networking security group rules that the tenant can access.

The list provides the UUID for each security group rule.

Normal response codes: 200

Error response codes: 401

Request

Response Parameters

Name In Type Description
remote_group_id (Optional) body string The remote group UUID to associate with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body.
direction body string Ingress or egress, which is the direction in which the metering rule is applied.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
ethertype (Optional) body string Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.
port_range_max (Optional) body integer The maximum port number in the range that is matched by the security group rule. The port_range_min attribute constrains the port_range_max attribute. If the protocol is ICMP, this value must be an ICMP type.
security_group_rules body array A list of security_group_rule objects.
security_group_id body string The security group UUID to associate with this security group rule.
tenant_id body string The ID of the tenant who owns the resource.
port_range_min (Optional) body integer The minimum port number in the range that is matched by the security group rule. If the protocol is TCP or UDP, this value must be less than or equal to the port_range_max attribute value. If the protocol is ICMP, this value must be an ICMP type.
remote_ip_prefix body string The remote IP prefix to associate with this metering rule packet.
id body string The UUID of the network.

Response Example

{
    "security_group_rules": [
        {
            "direction": "egress",
            "ethertype": "IPv6",
            "id": "3c0e45ff-adaf-4124-b083-bf390e5482ff",
            "port_range_max": null,
            "port_range_min": null,
            "protocol": null,
            "remote_group_id": null,
            "remote_ip_prefix": null,
            "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
            "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550"
        },
        {
            "direction": "egress",
            "ethertype": "IPv4",
            "id": "93aa42e5-80db-4581-9391-3a608bd0e448",
            "port_range_max": null,
            "port_range_min": null,
            "protocol": null,
            "remote_group_id": null,
            "remote_ip_prefix": null,
            "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
            "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550"
        },
        {
            "direction": "ingress",
            "ethertype": "IPv6",
            "id": "c0b09f00-1d49-4e64-a0a7-8a186d928138",
            "port_range_max": null,
            "port_range_min": null,
            "protocol": null,
            "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
            "remote_ip_prefix": null,
            "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
            "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550"
        },
        {
            "direction": "ingress",
            "ethertype": "IPv4",
            "id": "f7d45c89-008e-4bab-88ad-d6811724c51c",
            "port_range_max": null,
            "port_range_min": null,
            "protocol": null,
            "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
            "remote_ip_prefix": null,
            "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
            "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550"
        }
    ]
}
POST
/v2.0/security-group-rules

Create security group rule

Creates an OpenStack Networking security group rule.

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

Request

Name In Type Description
remote_group_id (Optional) body string The remote group UUID to associate with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body.
direction body string Ingress or egress, which is the direction in which the metering rule is applied.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
ethertype (Optional) body string Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.
port_range_max (Optional) body integer The maximum port number in the range that is matched by the security group rule. The port_range_min attribute constrains the port_range_max attribute. If the protocol is ICMP, this value must be an ICMP type.
security_group_id body string The security group UUID to associate with this security group rule.
security_group_rule body object A security_group_rule object.
port_range_min (Optional) body integer The minimum port number in the range that is matched by the security group rule. If the protocol is TCP or UDP, this value must be less than or equal to the port_range_max attribute value. If the protocol is ICMP, this value must be an ICMP type.
remote_ip_prefix body string The remote IP prefix to associate with this metering rule packet.

Request Example

{
    "security_group_rule": {
        "direction": "ingress",
        "port_range_min": "80",
        "ethertype": "IPv4",
        "port_range_max": "80",
        "protocol": "tcp",
        "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
        "security_group_id": "a7734e61-b545-452d-a3cd-0189cbd9747a"
    }
}

Response Parameters

Name In Type Description
remote_group_id (Optional) body string The remote group UUID to associate with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body.
direction body string Ingress or egress, which is the direction in which the metering rule is applied.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
ethertype (Optional) body string Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.
port_range_max (Optional) body integer The maximum port number in the range that is matched by the security group rule. The port_range_min attribute constrains the port_range_max attribute. If the protocol is ICMP, this value must be an ICMP type.
security_group_id body string The security group UUID to associate with this security group rule.
security_group_rule body object A security_group_rule object.
tenant_id body string The ID of the tenant who owns the resource.
port_range_min (Optional) body integer The minimum port number in the range that is matched by the security group rule. If the protocol is TCP or UDP, this value must be less than or equal to the port_range_max attribute value. If the protocol is ICMP, this value must be an ICMP type.
remote_ip_prefix body string The remote IP prefix to associate with this metering rule packet.
id body string The UUID of the network.

Quotas extension (quotas)

Lists default quotas, current quotas for tenants who have non-default quota values, and shows, updates, and resets quotas for a tenant.

A quota value of -1 means that quota has no limit.

GET
/v2.0/quotas

List quotas for tenants with non-default quota values

Lists quotas for tenants who have non-default quota values.

Normal response codes: 200

Error response codes: 401, 403

Request

Response Parameters

Name In Type Description
subnet body integer The number of subnets allowed for each tenant.
network body integer The number of networks allowed for each tenant.
floatingip body integer The number of floating IP addresses allowed for each tenant. A value of -1 means no limit.
subnetpool body integer The number of subnet pools allowed for each tenant.
quotas body array A list of quota objects.
security_group_rule body integer The number of security group rules allowed for each tenant.
security_group body integer The number of security groups allowed for each tenant.
router body integer The number of routers allowed for each tenant.
rbac_policy body integer The number of role-based access control (RBAC) policies for each tenant.
port body integer The number of ports allowed for each tenant.

Response Example

{
    "quotas": [
        {
            "subnet": 10,
            "network": 15,
            "floatingip": 50,
            "tenant_id": "bab7d5c60cd041a0a36f7c4b6e1dd978",
            "subnetpool": -1,
            "security_group_rule": 100,
            "security_group": 10,
            "router": 10,
            "rbac_policy": -1,
            "port": 50
        }
    ]
}
GET
/v2.0/quotas/{tenant_id}

List quotas for a tenant

Lists quotas for a tenant.

Normal response codes: 200

Error response codes: 401, 403, 404

Request

Name In Type Description
tenant_id path string The ID of the tenant.

Response Parameters

Name In Type Description
subnet body integer The number of subnets allowed for each tenant.
network body integer The number of networks allowed for each tenant.
floatingip body integer The number of floating IP addresses allowed for each tenant. A value of -1 means no limit.
subnetpool body integer The number of subnet pools allowed for each tenant.
quotas body array A list of quota objects.
security_group_rule body integer The number of security group rules allowed for each tenant.
security_group body integer The number of security groups allowed for each tenant.
router body integer The number of routers allowed for each tenant.
rbac_policy body integer The number of role-based access control (RBAC) policies for each tenant.
port body integer The number of ports allowed for each tenant.

Response Example

{
    "quota": {
        "subnet": 10,
        "network": 10,
        "floatingip": 50,
        "subnetpool": -1,
        "security_group_rule": 100,
        "security_group": 10,
        "router": 10,
        "rbac_policy": -1,
        "port": 50
    }
}
PUT
/v2.0/quotas/{tenant_id}

Update quota for a tenant

Updates quotas for a tenant. Use when non-default quotas are desired.

Normal response codes: 200

Error response codes: 401, 403, 404

Request

Name In Type Description
subnet body integer The number of subnets allowed for each tenant.
network body integer The number of networks allowed for each tenant.
floatingip body integer The number of floating IP addresses allowed for each tenant. A value of -1 means no limit.
subnetpool body integer The number of subnet pools allowed for each tenant.
quotas body array A list of quota objects.
security_group_rule body integer The number of security group rules allowed for each tenant.
security_group body integer The number of security groups allowed for each tenant.
router body integer The number of routers allowed for each tenant.
rbac_policy body integer The number of role-based access control (RBAC) policies for each tenant.
port body integer The number of ports allowed for each tenant.
tenant_id body string The ID of the tenant who owns the resource.

Request Example

{
    "quota": {
        "subnet": 10,
        "network": 10,
        "floatingip": 50,
        "subnetpool": -1,
        "security_group_rule": 100,
        "security_group": 10,
        "router": 10,
        "rbac_policy": -1,
        "port": 50
    }
}

Response Parameters

Name In Type Description
subnet body integer The number of subnets allowed for each tenant.
network body integer The number of networks allowed for each tenant.
floatingip body integer The number of floating IP addresses allowed for each tenant. A value of -1 means no limit.
subnetpool body integer The number of subnet pools allowed for each tenant.
quotas body array A list of quota objects.
security_group_rule body integer The number of security group rules allowed for each tenant.
security_group body integer The number of security groups allowed for each tenant.
router body integer The number of routers allowed for each tenant.
rbac_policy body integer The number of role-based access control (RBAC) policies for each tenant.
port body integer The number of ports allowed for each tenant.
tenant_id body string The ID of the tenant who owns the resource.

Response Example

{
    "quota": {
        "subnet": 10,
        "network": 15,
        "floatingip": 50,
        "subnetpool": -1,
        "security_group_rule": 100,
        "security_group": 10,
        "router": 10,
        "rbac_policy": -1,
        "port": 50
    }
}
DELETE
/v2.0/quotas/{tenant_id}

Reset quota for a tenant

Resets quotas to default values for a tenant.

Error response codes: 204, 401, 403, 404

Request

Name In Type Description
tenant_id path string The ID of the tenant.
GET
/v2.0/quotas/{tenant_id}/default

List default quotas for a tenant

Lists default quotas for a tenant.

Normal response codes: 200

Error response codes: 401, 403, 404

Request

Name In Type Description
tenant_id path string The ID of the tenant.

Response Parameters

Name In Type Description
quota body object A quota object.
floatingip body integer The number of floating IP addresses allowed for each tenant. A value of -1 means no limit.
network body integer The number of networks allowed for each tenant.
port body integer The number of ports allowed for each tenant.
rbac_policy body integer The number of role-based access control (RBAC) policies for each tenant.
router body integer The number of routers allowed for each tenant.
security_group body integer The number of security groups allowed for each tenant.
security_group_rule body integer The number of security group rules allowed for each tenant.
subnet body integer The number of subnets allowed for each tenant.
subnetpool body integer The number of subnet pools allowed for each tenant.

Response Example

{
    "quota": {
        "subnet": 10,
        "network": 10,
        "floatingip": 50,
        "subnetpool": -1,
        "security_group_rule": 100,
        "security_group": 10,
        "router": 10,
        "rbac_policy": -1,
        "port": 50
    }
}

Service providers

Lists service providers.

GET
/v2.0/service-providers

List service providers

Lists service providers and their associated service types.

Normal response codes: 200

Error response codes: 404,409,401,400

Request

Response Parameters

Name In Type Description
default body boolean Defines whether the provider is the default for the service type. If this value is true, the provider is the default. If this value is false, the provider is not the default.
service_type body string The service type, which is CORE, DUMMY, FIREWALL, FLAVORS, L3_ROUTER_NAT, LOADBALANCER, LOADBALANCERV2, METERING, QOS, or VPN.
service_providers body array A list of service_provider objects.
name body string Human-readable name of the resource.

Response Example

{
    "service_providers": [
        {
            "service_type": "LOADBALANCER",
            "default": true,
            "name": "haproxy"
        }
    ]
}

Networking Flavors Framework v2.0 (CURRENT) (flavor, service_profile)

Extension that allows user selection of operator-curated flavors during resource creation.

Service q-flavors must be enabled in the configuration to use this feature.

DELETE
/v2.0/flavors/{flavor_id}/service_profiles/{profile_id}

Disassociate a flavor.

Disassociate a flavor from a service profile.

Error response codes: 404,403,204,401

Request

Name In Type Description
profile_id (Optional) path string The UUID of the profile.
flavor_id (Optional) path string The UUID of the flavor.
GET
/v2.0/service_profiles/{profile_id}

Show service profile details

Shows details for a service profile.

This operation returns a service profile object by ID. If you are not an administrative user and the object is not visible to your tenant account, the service returns the HTTP Forbidden (403) response code.

Normal response codes: 200

Error response codes: 404,403,401

Request

Name In Type Description
profile_id (Optional) path string The UUID of the profile.

Response Parameters

Name In Type Description
description body string The human-readable description for the resource.
driver (Optional) body string Provider driver to use for this profile. Example: neutron_lbaas.drivers.octavia.driver.OctaviaDriver
enabled (Optional) body boolean Set to false to disable this rule in the firewall policy. Facilitates selectively turning off rules without having to disassociate the rule from the firewall policy. Valid value is true or false. Default is true.
metainfo (Optional) body string JSON-formatted meta information.
service_profile body object A service_profile object.
id body string The UUID of the network.

Response Example

{
    "service_profile": {
        "enabled": true,
        "metainfo": "{'foo': 'bar'}",
        "driver": "neutron_lbaas.drivers.octavia.driver.OctaviaDriver",
        "id": "7c793e5f-9b64-44e0-8b1f-902e59c85a01",
        "description": "Dummy profile"
    }
}
PUT
/v2.0/service_profiles/{profile_id}

Update service profile

Updates a service profile.

Normal response codes: 200 Error response codes: 404,403,401,400

Request

Name In Type Description
service_profile body object A service_profile object.
enabled (Optional) body boolean Set to false to disable this rule in the firewall policy. Facilitates selectively turning off rules without having to disassociate the rule from the firewall policy. Valid value is true or false. Default is true.
driver (Optional) body string Provider driver to use for this profile. Example: neutron_lbaas.drivers.octavia.driver.OctaviaDriver
description body string The human-readable description for the resource.
metainfo (Optional) body string JSON-formatted meta information.
profile_id (Optional) path string The UUID of the profile.

Request Example

{
    "service_profile": {
        "enabled": false,
        "driver": "neutron_lbaas.drivers.octavia.driver.OctaviaDriver",
        "description": "New description",
        "metainfo": "{'new': 'info'}"
    }
}

Response Parameters

Name In Type Description
description body string The human-readable description for the resource.
driver (Optional) body string Provider driver to use for this profile. Example: neutron_lbaas.drivers.octavia.driver.OctaviaDriver
enabled (Optional) body boolean Set to false to disable this rule in the firewall policy. Facilitates selectively turning off rules without having to disassociate the rule from the firewall policy. Valid value is true or false. Default is true.
metainfo (Optional) body string JSON-formatted meta information.
service_profile body object A service_profile object.
id body string The UUID of the network.

Response Example

{
    "service_profile": {
        "enabled": false,
        "metainfo": "{'new': 'info'}",
        "driver": "neutron_lbaas.drivers.octavia.driver.OctaviaDriver",
        "id": "7c793e5f-9b64-44e0-8b1f-902e59c85a01",
        "description": "New description"
    }
}
DELETE
/v2.0/service_profiles/{profile_id}

Delete service profile

Deletes a service profile.

Attempting to delete a service profile that is currently associated with a flavor will return a Conflict 409 with a response body containing an in use message.

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

Request

Name In Type Description
profile_id (Optional) path string The UUID of the profile.
GET
/v2.0/service_profiles

List service profiles

Lists all service profiles visible for the tenant account.

The list can be empty.

Standard query parameters are supported on the URI.

Normal response codes: 200

Error response codes: 401

Request

Response Parameters

Name In Type Description
description body string The human-readable description for the resource.
driver (Optional) body string Provider driver to use for this profile. Example: neutron_lbaas.drivers.octavia.driver.OctaviaDriver
enabled (Optional) body boolean Set to false to disable this rule in the firewall policy. Facilitates selectively turning off rules without having to disassociate the rule from the firewall policy. Valid value is true or false. Default is true.
metainfo (Optional) body string JSON-formatted meta information.
service_profiles body array Service profile UUIDs associated with this flavor.
id body string The UUID of the network.

Response Example

{
    "service_profiles": [
        {
            "id": "4e5b9191-ffbe-4f7a-b112-2db98232fd32",
            "enabled": true,
            "driver": "neutron_lbaas.drivers.octavia.driver.OctaviaDriver",
            "description": "",
            "metainfo": ""
        },
        {
            "id": "684322c5-703a-48a2-8138-34b99942a7ef",
            "enabled": true,
            "driver": "neutron_lbaas.drivers.octavia.driver.OctaviaDriver",
            "description": "",
            "metainfo": ""
        }
    ]
}
POST
/v2.0/service_profiles

Create service profile

Creates a service profile.

This operation establishes a new service profile that can be associated with one or more flavors.

Either metadata or a driver is required.

If a driver is specified but does not exist, call will return a Not found 404 error with the response body explaining that the driver could not be found.

Creation currently limited to administrators. Other users will receive a Forbidden 403 response code with a response body NeutronError message expressing that creation is disallowed by policy.

If the API cannot fulfill the request due to insufficient data or data that is not valid, the service returns the HTTP Bad Request (400) response code with information about the failure in the response body. Validation errors require that you correct the error and submit the request again.

Error response codes: 201,403,401,400

Request

Name In Type Description
service_profile body object A service_profile object.
enabled (Optional) body boolean Set to false to disable this rule in the firewall policy. Facilitates selectively turning off rules without having to disassociate the rule from the firewall policy. Valid value is true or false. Default is true.
driver (Optional) body string Provider driver to use for this profile. Example: neutron_lbaas.drivers.octavia.driver.OctaviaDriver
description body string The human-readable description for the resource.
metainfo (Optional) body string JSON-formatted meta information.

Request Example

{
    "service_profile": {
        "enabled": "true",
        "driver": "neutron_lbaas.drivers.octavia.driver.OctaviaDriver",
        "description": "Dummy profile",
        "metainfo": "{'foo': 'bar'}"
    }
}

Response Parameters

Name In Type Description
description body string The human-readable description for the resource.
driver (Optional) body string Provider driver to use for this profile. Example: neutron_lbaas.drivers.octavia.driver.OctaviaDriver
enabled (Optional) body boolean Set to false to disable this rule in the firewall policy. Facilitates selectively turning off rules without having to disassociate the rule from the firewall policy. Valid value is true or false. Default is true.
metainfo (Optional) body string JSON-formatted meta information.
service_profile body object A service_profile object.
id body string The UUID of the network.
GET
/v2.0/flavors

List flavors

Lists all flavors visible for the tenant account.

The list can be empty.

Standard query parameters are supported on the URI. For example, fields can be used to limit the returned response to just name by appending ?fields=name. If Neutron configuration supports pagination by overriding allow_pagination = false, the marker query parameter can set the last element id the client has seen and limit set the maximum number of items to return. if Neutron configuration has allow_sorting = true, sort_key and sort_dir pairs can be used where sort direction is ‘asc’ or ‘desc’.

Normal response codes: 200

Error response codes: 401

Request

Response Parameters

Name In Type Description
flavors body array A list of flavor objects.
description body string The human-readable description for the resource.
enabled (Optional) body boolean Set to false to disable this rule in the firewall policy. Facilitates selectively turning off rules without having to disassociate the rule from the firewall policy. Valid value is true or false. Default is true.
service_profiles body array Service profile UUIDs associated with this flavor.
service_type body string The service type, which is CORE, DUMMY, FIREWALL, FLAVORS, L3_ROUTER_NAT, LOADBALANCER, LOADBALANCERV2, METERING, QOS, or VPN.
id body string The UUID of the network.
name body string Human-readable name of the resource.

Response Example

{
    "flavors": [
        {
            "description": "",
            "enabled": true,
            "service_profiles": [],
            "service_type": "LOADBALANCERV2",
            "id": "f7b14d9a-b0dc-4fbe-bb14-a0f4970a69e0",
            "name": "dummy"
        }
    ]
}
POST
/v2.0/flavors

Create flavor

Creates a flavor.

This operation establishes a new flavor.

The service_type to which the flavor applies is a required parameter. The corresponding service plugin must have been activated as part of the configuration. See Service providers for how to see currently loaded service types. Additionally the service plugin needs to support the use of flavors. For example, the LOADBALANCERV2 service type using the LBaaSv2 API currently supports Neutron service flavors.

Creation currently limited to administrators. Other users will receive a Forbidden 403 response code with a response body NeutronError message expressing that creation is disallowed by policy.

Until one or more service profiles are associated with the flavor by the operator, attempts to use the flavor during resource creations will currently return a Not Found 404 with a response body that indicates no service profile could be found.

If the API cannot fulfill the request due to insufficient data or data that is not valid, the service returns the HTTP Bad Request (400) response code with information about the failure in the response body. Validation errors require that you correct the error and submit the request again.

Error response codes: 201,403,401,400

Request

Name In Type Description
service_type body string The service type, which is CORE, DUMMY, FIREWALL, FLAVORS, L3_ROUTER_NAT, LOADBALANCER, LOADBALANCERV2, METERING, QOS, or VPN.
flavor body object A flavor object.
enabled (Optional) body boolean Set to false to disable this rule in the firewall policy. Facilitates selectively turning off rules without having to disassociate the rule from the firewall policy. Valid value is true or false. Default is true.
description body string The human-readable description for the resource.
name body string Human-readable name of the resource.

Request Example

{
    "flavor": {
        "service_type": "LOADBALANCERV2",
        "enabled": true,
        "name": "dummy",
        "description": "Dummy flavor"
    }
}

Response Parameters

Name In Type Description
description body string The human-readable description for the resource.
enabled (Optional) body boolean Set to false to disable this rule in the firewall policy. Facilitates selectively turning off rules without having to disassociate the rule from the firewall policy. Valid value is true or false. Default is true.
service_profiles body array Service profile UUIDs associated with this flavor.
service_type body string The service type, which is CORE, DUMMY, FIREWALL, FLAVORS, L3_ROUTER_NAT, LOADBALANCER, LOADBALANCERV2, METERING, QOS, or VPN.
flavor body object A flavor object.
id body string The UUID of the network.
name body string Human-readable name of the resource.
POST
/v2.0/flavors/{flavor_id}/service_profiles

Associate flavor

Associate a flavor with a service profile.

A flavor can be associated with more than one profile.

Will return 409 Conflict if association already exists.

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

Request

Name In Type Description
service_profile body object A service_profile object.
id body string The UUID of the network.
flavor_id (Optional) path string The UUID of the flavor.

Request Example

{
    "service_profile": {
        "id": "4e5b9191-ffbe-4f7a-b112-2db98232fd32"
    }
}

Response Parameters

Name In Type Description
service_profile body object A service_profile object.
id body string The UUID of the network.
GET
/v2.0/flavors/{flavor_id}

Show flavor details

Shows details for a flavor.

This operation returns a flavor object by ID. If you are not an administrative user and the flavor object is not visible to your tenant account, the service returns the HTTP Forbidden (403) response code.

Normal response codes: 200

Error response codes: 404,403,401

Request

Name In Type Description
flavor_id (Optional) path string The UUID of the flavor.

Response Parameters

Name In Type Description
description body string The human-readable description for the resource.
enabled (Optional) body boolean Set to false to disable this rule in the firewall policy. Facilitates selectively turning off rules without having to disassociate the rule from the firewall policy. Valid value is true or false. Default is true.
service_profiles body array Service profile UUIDs associated with this flavor.
service_type body string The service type, which is CORE, DUMMY, FIREWALL, FLAVORS, L3_ROUTER_NAT, LOADBALANCER, LOADBALANCERV2, METERING, QOS, or VPN.
flavor body object A flavor object.
id body string The UUID of the network.
name body string Human-readable name of the resource.

Response Example

{
    "flavor": {
        "description": "",
        "enabled": true,
        "service_profiles": [],
        "service_type": "LOADBALANCERV2",
        "id": "f7b14d9a-b0dc-4fbe-bb14-a0f4970a69e0",
        "name": "dummy"
    }
}
PUT
/v2.0/flavors/{flavor_id}

Update flavor

Updates a flavor.

The service_type cannot be updated as there may be associated service profiles and consumers depending on the value.

Normal response codes: 200

Error response codes: 404,403,401,400

Request

Name In Type Description
flavor body object A flavor object.
enabled (Optional) body boolean Set to false to disable this rule in the firewall policy. Facilitates selectively turning off rules without having to disassociate the rule from the firewall policy. Valid value is true or false. Default is true.
description body string The human-readable description for the resource.
name body string Human-readable name of the resource.
flavor_id (Optional) path string The UUID of the flavor.

Request Example

{
    "flavor": {
        "enabled": false,
        "name": "newname",
        "description": "New description"
    }
}

Response Parameters

Name In Type Description
description body string The human-readable description for the resource.
enabled (Optional) body boolean Set to false to disable this rule in the firewall policy. Facilitates selectively turning off rules without having to disassociate the rule from the firewall policy. Valid value is true or false. Default is true.
service_profiles body array Service profile UUIDs associated with this flavor.
service_type body string The service type, which is CORE, DUMMY, FIREWALL, FLAVORS, L3_ROUTER_NAT, LOADBALANCER, LOADBALANCERV2, METERING, QOS, or VPN.
flavor body object A flavor object.
id body string The UUID of the network.
name body string Human-readable name of the resource.

Response Example

{
    "flavor": {
        "description": "New description",
        "enabled": false,
        "service_profiles": [],
        "service_type": "LOADBALANCERV2",
        "id": "7fc0581b-4509-49e1-90eb-c953c877fa4c",
        "name": "newname"
    }
}
DELETE
/v2.0/flavors/{flavor_id}

Delete flavor

Deletes a flavor.

Error response codes: 404,403,204,401

Request

Name In Type Description
flavor_id (Optional) path string The UUID of the flavor.

Tag extension (tags)

Shows details for, updates, and deletes tags. This extension is available since Mitaka release.

PUT
/v2.0/{resource_type}/{resource_id}/tags

Replace all tags

Replaces all tags on the resource.

Normal response codes: 200

Error response codes: 404,401,400,503,500

Request

Name In Type Description
tags body array The list of tags on the resource.
resource_type (Optional) path string The type of resource which the tag is set on.
resource_id (Optional) path string The UUID of resource which the tag is set on.

Request Example

{
    "tags": [
        "red",
        "blue"
    ]
}

Response Parameters

Name In Type Description
tags body array The list of tags on the resource.

Response Example

{
    "tags": [
        "red",
        "blue"
    ]
}
DELETE
/v2.0/{resource_type}/{resource_id}/tags

Remove all tags

Removes all tags on the resource.

Error response codes: 500,404,204,401,503

Request

Name In Type Description
resource_type (Optional) path string The type of resource which the tag is set on.
resource_id (Optional) path string The UUID of resource which the tag is set on.
GET
/v2.0/{resource_type}/{resource_id}/tags/{tag}

Confirm a tag

Confirms a given tag is set on the resource.

Error response codes: 500,404,204,401,503

Request

Name In Type Description
tag (Optional) path string The name for the tag.
resource_type (Optional) path string The type of resource which the tag is set on.
resource_id (Optional) path string The UUID of resource which the tag is set on.
PUT
/v2.0/{resource_type}/{resource_id}/tags/{tag}

Add a tag

Adds a tag on the resource.

Error response codes: 201,404,500,401,503

Request

Name In Type Description
tag (Optional) path string The name for the tag.
resource_type (Optional) path string The type of resource which the tag is set on.
resource_id (Optional) path string The UUID of resource which the tag is set on.
DELETE
/v2.0/{resource_type}/{resource_id}/tags/{tag}

Remove a tag

Removes a tag on the resource.

Error response codes: 500,404,204,401,503

Request

Name In Type Description
tag (Optional) path string The name for the tag.
resource_type (Optional) path string The type of resource which the tag is set on.
resource_id (Optional) path string The UUID of resource which the tag is set on.

Network IP availability and usage stats

List and show the network IP usage stats of all networks and a specified network. These operations are available in the Mitaka release (April 2016).

GET
/v2.0/network-ip-availabilities/{network_id}

Show Network IP Availability

Shows network IP availability details for a network.

Normal response codes: 200

Error response codes: 403,401

Request

Name In Type Description
network_id (Optional) path string The UUID of the network.

Response Parameters

Name In Type Description
used_ips body integer The number of used IP addresses of all subnets in a network.
subnet_ip_availability body array This is dictionary showing subnet IP availability. It contains information for every subnet associated to each network as described in the parameters.
network_id (Optional) path string The UUID of the network.
tenant_id body string The ID of the tenant who owns the resource.
total_ips body integer The total number of IP addresses in a network.
network_ip_availability body object A network_ip_availability object.
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
subnet_name body string The name of the subnet.
ip_version (Optional) body integer The IP protocol version. Valid value is 4 or 6. Default is 4.
cidr body string The CIDR of the subnet.
network_name body string The name of the network.

Response Example

{
    "network_ip_availability": {
        "used_ips": 4,
        "subnet_ip_availability": [
            {
                "used_ips": 2,
                "subnet_id": "44e70d00-80a2-4fb1-ab59-6190595ceb61",
                "subnet_name": "private-subnet",
                "ip_version": 4,
                "cidr": "10.0.0.0/24",
                "total_ips": 253
            },
            {
                "used_ips": 2,
                "subnet_id": "a90623df-00e1-4902-a675-40674385d74c",
                "subnet_name": "ipv6-private-subnet",
                "ip_version": 6,
                "cidr": "fdbf:ac66:9be8::/64",
                "total_ips": 18446744073709552000
            }
        ],
        "network_id": "6801d9c8-20e6-4b27-945d-62499f00002e",
        "tenant_id": "d56d3b8dd6894a508cf41b96b522328c",
        "total_ips": 18446744073709552000,
        "network_name": "private"
    }
}
GET
/v2.0/network-ip-availabilities

List Network IP Availability

Lists network IP availability of all networks.

Normal response codes: 200

Error response codes: 403,401

Request

Response Parameters

Name In Type Description
used_ips body integer The number of used IP addresses of all subnets in a network.
subnet_ip_availability body array This is dictionary showing subnet IP availability. It contains information for every subnet associated to each network as described in the parameters.
network_id (Optional) path string The UUID of the network.
tenant_id body string The ID of the tenant who owns the resource.
total_ips body integer The total number of IP addresses in a network.
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
subnet_name body string The name of the subnet.
ip_version (Optional) body integer The IP protocol version. Valid value is 4 or 6. Default is 4.
cidr body string The CIDR of the subnet.
network_name body string The name of the network.
network_ip_availabilities body array The network_ip_availabilities object.

Response Example

{
    "network_ip_availabilities": [
        {
            "network_id": "4cf895c9-c3d1-489e-b02e-59b5c8976809",
            "network_name": "public",
            "subnet_ip_availability": [
                {
                    "cidr": "2001:db8::/64",
                    "ip_version": 6,
                    "subnet_id": "ca3f46c4-c6ff-4272-9be4-0466f84c6077",
                    "subnet_name": "ipv6-public-subnet",
                    "total_ips": 18446744073709552000,
                    "used_ips": 1
                },
                {
                    "cidr": "172.24.4.0/24",
                    "ip_version": 4,
                    "subnet_id": "cc02efc1-9d47-46bd-bab6-760919c836b5",
                    "subnet_name": "public-subnet",
                    "total_ips": 253,
                    "used_ips": 1
                }
            ],
            "tenant_id": "1a02cc95f1734fcc9d3c753818f03002",
            "total_ips": 253,
            "used_ips": 2
        },
        {
            "network_id": "6801d9c8-20e6-4b27-945d-62499f00002e",
            "network_name": "private",
            "subnet_ip_availability": [
                {
                    "cidr": "10.0.0.0/24",
                    "ip_version": 4,
                    "subnet_id": "44e70d00-80a2-4fb1-ab59-6190595ceb61",
                    "subnet_name": "private-subnet",
                    "total_ips": 253,
                    "used_ips": 2
                },
                {
                    "ip_version": 6,
                    "cidr": "fdbf:ac66:9be8::/64",
                    "subnet_id": "a90623df-00e1-4902-a675-40674385d74c",
                    "subnet_name": "ipv6-private-subnet",
                    "total_ips": 18446744073709552000,
                    "used_ips": 2
                }
            ],
            "tenant_id": "d56d3b8dd6894a508cf41b96b522328c",
            "total_ips": 18446744073709552000,
            "used_ips": 4
        }
    ]
}

QoS policies (qos)

Lists, creates, shows information for, and updates QoS policies.

GET
/v2.0/qos/policies/{policy_id}/bandwidth_limit_rules/{rule_id}

Show bandwidth limit rule details

Shows details for a bandwidth limit rule for a QoS policy.

Normal response codes: 200

Error response codes: 500,401,503

Request

Name In Type Description
rule_id (Optional) path string The UUID of the rule.
policy_id (Optional) path string The UUID of the policy.

Response Parameters

Name In Type Description
bandwidth_limit_rule body object A bandwidth_limit_rule object.
max_kbps (Optional) body integer The maximum KBPS value. If you specify this value, must be greater than 0. Default is null.
id body string The UUID of the network.
max_burst_kbps (Optional) body integer The burst over the maximum KBPS value. Default is 0
policy_id (Optional) path string The UUID of the policy.

Response Example

{
    "bandwidth_limit_rule": {
        "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c793",
        "policy_id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
        "max_kbps": "10000",
        "max_burst_kbps": "0"
    }
}
PUT
/v2.0/qos/policies/{policy_id}/bandwidth_limit_rules/{rule_id}

Update bandwidth limit rule

Updates a bandwidth limit rule for a QoS policy.

If the request is valid, the service returns the Accepted (202) response code.

Normal response codes: 200

Error response codes: 400,401,413,503,500

Request

Name In Type Description
bandwidth_limit_rule body object A bandwidth_limit_rule object.
max_kbps (Optional) body integer The maximum KBPS value. If you specify this value, must be greater than 0. Default is null.
max_burst_kbps (Optional) body integer The burst over the maximum KBPS value. Default is 0
policy_id (Optional) path string The UUID of the policy.
rule_id (Optional) path string The UUID of the rule.
policy_id (Optional) path string The UUID of the policy.

Request Example

{
    "bandwidth_limit_rule": {
        "max_kbps": "10000"
    }
}

Response Parameters

Name In Type Description
bandwidth_limit_rule body object A bandwidth_limit_rule object.
max_kbps (Optional) body integer The maximum KBPS value. If you specify this value, must be greater than 0. Default is null.
id body string The UUID of the network.
max_burst_kbps (Optional) body integer The burst over the maximum KBPS value. Default is 0
policy_id (Optional) path string The UUID of the policy.

Response Example

{
    "bandwidth_limit_rule": {
        "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c793",
        "policy_id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
        "max_kbps": "10000",
        "max_burst_kbps": "0"
    }
}
DELETE
/v2.0/qos/policies/{policy_id}/bandwidth_limit_rules/{rule_id}

Delete bandwidth limit rule

Deletes a bandwidth limit rule for a QoS policy.

Error response codes: 204,400,401,413,503,500

Request

Name In Type Description
rule_id (Optional) path string The UUID of the rule.
policy_id (Optional) path string The UUID of the policy.
GET
/v2.0/qos/policies

List QoS policies

Lists all QoS policies that are associated with your tenant account.

The list might be empty.

Normal response codes: 200

Error response codes: 500,401,503

Request

Response Parameters

Name In Type Description
max_kbps (Optional) body integer The maximum KBPS value. If you specify this value, must be greater than 0. Default is null.
bandwidth_limit_rules body array A list of bandwidth limit rules associated with the QoS policy.
description body string The human-readable description for the resource.
policy_id (Optional) path string The UUID of the policy.
tenant_id body string The ID of the tenant who owns the resource.
dscp_marking_rules body array A list of dscp_marking_rule objects.
policies body array A list of QoS policy objects.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
dscp_mark (Optional) body integer The DSCP mark value.
id body string The UUID of the network.
max_burst_kbps (Optional) body integer The burst over the maximum KBPS value. Default is 0
name body string Human-readable name of the resource.

Response Example

{
    "policies": [
        {
            "tenant_id": "8d4c70a21fed4aeba121a1a429ba0d04",
            "id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
            "name": "10Mbit",
            "description": "This policy limits the ports to 10Mbit max.",
            "shared": false,
            "bandwidth_limit_rules": [
                {
                    "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c793",
                    "policy_id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
                    "max_kbps": "10000",
                    "max_burst_kbps": "0"
                }
            ],
            "dscp_marking_rules": [
                {
                    "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c794",
                    "policy_id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
                    "dscp_mark": "26"
                }
            ]
        }
    ]
}
POST
/v2.0/qos/policies

Create QoS policy

Creates a QoS policy.

Creates a QoS policy by using the configuration that you define in the request object. A response object is returned. The object contains a unique ID.

If the caller is not an administrative user, this call returns the HTTP Forbidden (403) response code.

Users with an administrative role can create policies on behalf of other tenants by specifying a tenant UUID that is different than their own.

Error response codes: 201,404,409,401,413,503,500

Request

Name In Type Description
description body string The human-readable description for the resource.
tenant_id body string The ID of the tenant who owns the resource.
policy body object A QoS policy object.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
type body string The type of probe sent by the load balancer to verify the member state. A valid value is PING, TCP, HTTP, or HTTPS.
name body string Human-readable name of the resource.

Request Example

{
    "policy": {
        "name": "10Mbit",
        "description": "This policy limits the ports to 10Mbit max.",
        "shared": false
    }
}

Response Parameters

Name In Type Description
description body string The human-readable description for the resource.
tenant_id body string The ID of the tenant who owns the resource.
policy body object A QoS policy object.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
id body string The UUID of the network.
name body string Human-readable name of the resource.
GET
/v2.0/qos/policies/{policy_id}/dscp_marking_rules/{dscp_rule_id}

Show DSCP marking rule details

Shows details for a DSCP marking rule for a QoS policy.

Normal response codes: 200

Error response codes: 500,401,503

Request

Name In Type Description
policy_id (Optional) path string The UUID of the policy.

Response Parameters

Name In Type Description
dscp_marking_rule body object A dscp_marking_rule object.
dscp_mark (Optional) body integer The DSCP mark value.
id body string The UUID of the network.
policy_id (Optional) path string The UUID of the policy.

Response Example

{
    "dscp_marking_rule": {
        "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c794",
        "policy_id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
        "dscp_mark": "26"
    }
}
PUT
/v2.0/qos/policies/{policy_id}/dscp_marking_rules/{dscp_rule_id}

Update DSCP marking rule

Updates a DSCP marking rule for a QoS policy.

If the request is valid, the service returns the Accepted (202) response code.

Normal response codes: 200

Error response codes: 400,401,413,503,500

Request

Name In Type Description
dscp_marking_rule body object A dscp_marking_rule object.
dscp_mark (Optional) body integer The DSCP mark value.
policy_id (Optional) path string The UUID of the policy.

Request Example

{
    "dscp_marking_rule": {
        "dscp_mark": "16"
    }
}

Response Parameters

Name In Type Description
dscp_marking_rule body object A dscp_marking_rule object.
dscp_mark (Optional) body integer The DSCP mark value.
id body string The UUID of the network.
policy_id (Optional) path string The UUID of the policy.

Response Example

{
    "dscp_marking_rule": {
        "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c794",
        "policy_id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
        "dscp_mark": "16"
    }
}
DELETE
/v2.0/qos/policies/{policy_id}/dscp_marking_rules/{dscp_rule_id}

Delete DSCP marking rule

Deletes a DSCP marking rule for a QoS policy.

Error response codes: 204,400,401,413,503,500

Request

Name In Type Description
policy_id (Optional) path string The UUID of the policy.
GET
/v2.0/qos/policies/{policy_id}/dscp_marking_rules

List DSCP marking rules for QoS policy

Lists all DSCP marking rules for a QoS policy.

The list may be empty.

Normal response codes: 200

Error response codes: 500,401,503

Request

Name In Type Description
policy_id (Optional) path string The UUID of the policy.

Response Parameters

Name In Type Description
dscp_marking_rules body array A list of dscp_marking_rule objects.
dscp_mark (Optional) body integer The DSCP mark value.
id body string The UUID of the network.
policy_id (Optional) path string The UUID of the policy.

Response Example

{
    "dscp_marking_rules": [
        {
            "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c794",
            "policy_id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
            "dscp_mark": "26"
        }
    ]
}
POST
/v2.0/qos/policies/{policy_id}/dscp_marking_rules

Create DSCP marking rule

Creates a DSCP marking rule for a QoS policy.

Error response codes: 201,404,409,401,413,503,500

Request

Name In Type Description
dscp_marking_rule body object A dscp_marking_rule object.
dscp_mark (Optional) body integer The DSCP mark value.
policy_id (Optional) path string The UUID of the policy.

Request Example

{
    "dscp_marking_rule": {
        "dscp_mark": "26"
    }
}

Response Parameters

Name In Type Description
dscp_marking_rule body object A dscp_marking_rule object.
dscp_mark (Optional) body integer The DSCP mark value.
id body string The UUID of the network.
policy_id (Optional) path string The UUID of the policy.
GET
/v2.0/qos/policies/{policy_id}

Show QoS policy details

Shows details for a QoS policy.

Normal response codes: 200

Error response codes: 500,401,503

Request

Name In Type Description
policy_id (Optional) path string The UUID of the policy.

Response Parameters

Name In Type Description
max_kbps (Optional) body integer The maximum KBPS value. If you specify this value, must be greater than 0. Default is null.
bandwidth_limit_rules body array A list of bandwidth limit rules associated with the QoS policy.
description body string The human-readable description for the resource.
policy_id (Optional) path string The UUID of the policy.
tenant_id body string The ID of the tenant who owns the resource.
dscp_marking_rules body array A list of dscp_marking_rule objects.
policy body object A QoS policy object.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
dscp_mark (Optional) body integer The DSCP mark value.
id body string The UUID of the network.
max_burst_kbps (Optional) body integer The burst over the maximum KBPS value. Default is 0
name body string Human-readable name of the resource.

Response Example

{
    "policy": {
        "tenant_id": "8d4c70a21fed4aeba121a1a429ba0d04",
        "id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
        "name": "10Mbit",
        "description": "This policy limits the ports to 10Mbit max.",
        "shared": false,
        "bandwidth_limit_rules": [
            {
                "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c793",
                "policy_id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
                "max_kbps": "10000",
                "max_burst_kbps": "0"
            }
        ],
        "dscp_marking_rules": [
            {
                "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c794",
                "policy_id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
                "dscp_mark": "26"
            }
        ]
    }
}
PUT
/v2.0/qos/policies/{policy_id}

Update QoS policy

Updates a QoS policy.

If the request is valid, the service returns the Accepted (202) response code.

Normal response codes: 200

Error response codes: 400,401,413,503,500

Request

Name In Type Description
description body string The human-readable description for the resource.
tenant_id body string The ID of the tenant who owns the resource.
policy body object A QoS policy object.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
type body string The type of probe sent by the load balancer to verify the member state. A valid value is PING, TCP, HTTP, or HTTPS.
name body string Human-readable name of the resource.
policy_id (Optional) path string The UUID of the policy.

Request Example

{
    "policy": {
        "name": "10Mbit",
        "description": "This policy limits the ports to 10Mbit max.",
        "shared": false
    }
}

Response Parameters

Name In Type Description
description body string The human-readable description for the resource.
tenant_id body string The ID of the tenant who owns the resource.
policy body object A QoS policy object.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
id body string The UUID of the network.
name body string Human-readable name of the resource.

Response Example

{
    "policy": {
        "name": "10Mbit",
        "description": "This policy limits the ports to 10Mbit max.",
        "id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
        "tenant_id": "8d4c70a21fed4aeba121a1a429ba0d04",
        "shared": false
    }
}
DELETE
/v2.0/qos/policies/{policy_id}

Delete QoS policy

Deletes a QoS policy.

Error response codes: 204,400,401,413,503,500

Request

Name In Type Description
policy_id (Optional) path string The UUID of the policy.
GET
/v2.0/qos/policies/{policy_id}/bandwidth_limit_rules

List bandwidth limit rules for QoS policy

Lists all bandwidth limit rules for a QoS policy.

The list might be empty.

Normal response codes: 200

Error response codes: 500,401,503

Request

Name In Type Description
policy_id (Optional) path string The UUID of the policy.

Response Parameters

Name In Type Description
max_kbps (Optional) body integer The maximum KBPS value. If you specify this value, must be greater than 0. Default is null.
bandwidth_limit_rules body array A list of bandwidth limit rules associated with the QoS policy.
id body string The UUID of the network.
max_burst_kbps (Optional) body integer The burst over the maximum KBPS value. Default is 0
policy_id (Optional) path string The UUID of the policy.

Response Example

{
    "bandwidth_limit_rules": [
        {
            "id": "5f126d84-551a-4dcf-bb01-0e9c0df0c793",
            "policy_id": "46ebaec0-0570-43ac-82f6-60d2b03168c4",
            "max_kbps": "10000",
            "max_burst_kbps": "0"
        }
    ]
}
POST
/v2.0/qos/policies/{policy_id}/bandwidth_limit_rules

Create bandwidth limit rule

Creates a bandwidth limit rule for a QoS policy.

Error response codes: 201,404,409,401,413,503,500

Request

Name In Type Description
bandwidth_limit_rule body object A bandwidth_limit_rule object.
max_kbps (Optional) body integer The maximum KBPS value. If you specify this value, must be greater than 0. Default is null.
max_burst_kbps (Optional) body integer The burst over the maximum KBPS value. Default is 0
policy_id (Optional) path string The UUID of the policy.

Request Example

{
    "bandwidth_limit_rule": {
        "max_kbps": "10000"
    }
}

Response Parameters

Name In Type Description
bandwidth_limit_rule body object A bandwidth_limit_rule object.
max_kbps (Optional) body integer The maximum KBPS value. If you specify this value, must be greater than 0. Default is null.
id body string The UUID of the network.
max_burst_kbps (Optional) body integer The burst over the maximum KBPS value. Default is 0
policy_id (Optional) path string The UUID of the policy.

Metering labels and rules (metering-labels, metering-label-rules)

Creates, modifies, and deletes OpenStack Layer3 metering labels and rules.

GET
/v2.0/metering/metering-labels

List metering labels

Lists all L3 metering labels that belong to the tenant.

The list shows the UUID for each metering label.

Normal response codes: 200

Error response codes: 401

Request

Response Parameters

Name In Type Description
description body string The human-readable description for the resource.
tenant_id body string The ID of the tenant who owns the resource.
metering_labels body array A list of metering_label objects.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
id body string The UUID of the network.
name body string Human-readable name of the resource.

Response Example

{
    "metering_labels": [
        {
            "tenant_id": "45345b0ee1ea477fac0f541b2cb79cd4",
            "description": "label1 description",
            "name": "label1",
            "id": "a6700594-5b7a-4105-8bfe-723b346ce866",
            "shared": false
        },
        {
            "tenant_id": "45345b0ee1ea477fac0f541b2cb79cd4",
            "description": "label2 description",
            "name": "label2",
            "id": "e131d186-b02d-4c0b-83d5-0c0725c4f812",
            "shared": false
        }
    ]
}
POST
/v2.0/metering/metering-labels

Create metering label

Creates an L3 metering label.

Error response codes: 201,403,401,400

Request

Name In Type Description
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
metering_label body object A metering_label object.
description body string The human-readable description for the resource.
name body string Human-readable name of the resource.

Request Example

{
    "metering_label": {
        "name": "label1",
        "description": "description of label1"
    }
}

Response Parameters

Name In Type Description
description body string The human-readable description for the resource.
tenant_id body string The ID of the tenant who owns the resource.
metering_label body object A metering_label object.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
id body string The UUID of the network.
name body string Human-readable name of the resource.
GET
/v2.0/metering/metering-labels/{metering-label-id}

Show metering label details

Shows details for a metering label.

The response body shows the description, name, and UUID.

Normal response codes: 200

Error response codes: 404,401

Request

Response Parameters

Name In Type Description
description body string The human-readable description for the resource.
tenant_id body string The ID of the tenant who owns the resource.
metering_label body object A metering_label object.
shared (Optional) body boolean Admin-only. Indicates whether this network is shared across all tenants.
id body string The UUID of the network.
name body string Human-readable name of the resource.

Response Example

{
    "metering_label": {
        "tenant_id": "45345b0ee1ea477fac0f541b2cb79cd4",
        "description": "label1 description",
        "name": "label1",
        "id": "a6700594-5b7a-4105-8bfe-723b346ce866",
        "shared": false
    }
}
DELETE
/v2.0/metering/metering-labels/{metering-label-id}

Delete metering label

Deletes an L3 metering label.

Error response codes: 404,204,401

Request

GET
/v2.0/metering/metering-label-rules

List metering label rules

Lists a summary of all L3 metering label rules that belong to the tenant.

The list shows the UUID for each metering label rule.

Normal response codes: 200

Error response codes: 401

Request

Response Parameters

Name In Type Description
direction body string Ingress or egress, which is the direction in which the metering rule is applied.
remote_ip_prefix body string The remote IP prefix to associate with this metering rule packet.
metering_label_rules body array A list of metering_label_rule objects.
excluded (Optional) body boolean Indicates whether to count the traffic of a specific IP address with the remote_ip_prefix value. Default is false.
metering_label_id body string The metering label UUID to associate with this metering rule.
id body string The UUID of the network.

Response Example

{
    "metering_label_rules": [
        {
            "remote_ip_prefix": "20.0.0.0/24",
            "direction": "ingress",
            "metering_label_id": "e131d186-b02d-4c0b-83d5-0c0725c4f812",
            "id": "9536641a-7d14-4dc5-afaf-93a973ce0eb8",
            "excluded": false
        },
        {
            "remote_ip_prefix": "10.0.0.0/24",
            "direction": "ingress",
            "metering_label_id": "e131d186-b02d-4c0b-83d5-0c0725c4f812",
            "id": "ffc6fd15-40de-4e7d-b617-34d3f7a93aec",
            "excluded": false
        }
    ]
}
POST
/v2.0/metering/metering-label-rules

Create metering label rule

Creates an L3 metering label rule.

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

Request

Name In Type Description
remote_ip_prefix body string The remote IP prefix to associate with this metering rule packet.
direction body string Ingress or egress, which is the direction in which the metering rule is applied.
metering_label_id body string The metering label UUID to associate with this metering rule.
metering_label_rule body object A metering_label_rule object.
excluded (Optional) body boolean Indicates whether to count the traffic of a specific IP address with the remote_ip_prefix value. Default is false.

Request Example

{
    "metering_label_rule": {
        "remote_ip_prefix": "10.0.1.0/24",
        "direction": "ingress",
        "metering_label_id": "e131d186-b02d-4c0b-83d5-0c0725c4f812"
    }
}

Response Parameters

Name In Type Description
direction body string Ingress or egress, which is the direction in which the metering rule is applied.
remote_ip_prefix body string The remote IP prefix to associate with this metering rule packet.
excluded (Optional) body boolean Indicates whether to count the traffic of a specific IP address with the remote_ip_prefix value. Default is false.
metering_label_id body string The metering label UUID to associate with this metering rule.
metering_label_rule body object A metering_label_rule object.
id body string The UUID of the network.
GET
/v2.0/metering/metering-label-rules/{metering-label-rule-id}

Show metering label rule details

Shows details for a metering label rule.

The response body shows this information for each metering label rule:

  • direction. Either ingress or egress.
  • excluded. Either true or false.
  • The UUID for the metering label rule.
  • The remote IP prefix.
  • The metering label ID for the metering label with which the rule is associated.

Normal response codes: 200

Error response codes: 404,401

Request

Response Example

{
    "metering_label_rule": {
        "remote_ip_prefix": "20.0.0.0/24",
        "direction": "ingress",
        "metering_label_id": "e131d186-b02d-4c0b-83d5-0c0725c4f812",
        "id": "9536641a-7d14-4dc5-afaf-93a973ce0eb8",
        "excluded": false
    }
}
DELETE
/v2.0/metering/metering-label-rules/{metering-label-rule-id}

Delete metering label rule

Deletes an L3 metering label rule.

Error response codes: 404,204,401

Request

LBaaS 2.0 (STABLE)

The Load-Balancer-as-a-Service (LBaaS) version 2.0 extension pairs with the Networking 2.0 API to enable OpenStack tenants to manage load balancers for their VMs. With this extension you can load- balance client traffic from one network to application services, such as VMs, on the same network.

Use this extension to create and manage load balancers, listeners, pools, members of a pool, and health monitors and view status of a resource.

Load balancer statuses

Status Description
ACTIVE The resource is ready and active.
PENDING_CREATE The resource is being created.
PENDING_UPDATE The resource is being updated.
PENDING_DELETE The resource is pending deletion.
INACTIVE The resource is not active.
ERROR An object within the service is not working. The error_details attribute provides an explanation for the error, its cause, and possibly a solution.
GET
/v2.0/lbaas/loadbalancers

List load balancers

Lists all load balancers for the tenant account.

The list might be empty.

Normal response codes: 200

Error response codes: 404,500,401,503

Request

Response Parameters

Name In Type Description
description body string The human-readable description for the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
loadbalancers body array A list of load balancer objects.
tenant_id body string The ID of the tenant who owns the resource.
provisioning_status body string The provisioning status of the load balancer. This value is ACTIVE, PENDING_CREATE or ERROR.
listeners body array The associated listeners, if any.
vip_address (Optional) body string The IP address of the VIP.
provider (Optional) body string The name of the provider.
vip_subnet_id body string The UUID of the subnet on which to allocate the virtual IP (VIP) address.
flavor body object A flavor object.
id body string The UUID of the network.
operating_status body string The operating status of the load balancer. This value is ONLINE or OFFLINE.
name body string Human-readable name of the resource.

Response Example

{
    "loadbalancers": [
        {
            "description": "simple lb",
            "admin_state_up": true,
            "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c",
            "provisioning_status": "ACTIVE",
            "listeners": [],
            "vip_address": "10.0.0.2",
            "vip_subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2",
            "id": "a9729389-6147-41a3-ab22-a24aed8692b2",
            "operating_status": "ONLINE",
            "name": "loadbalancer1"
        }
    ]
}
POST
/v2.0/lbaas/loadbalancers

Create load balancer

Creates a load balancer.

This operation provisions a new load balancer by using the configuration that you define in the request object. After the API validates the request and starts the provisioning process, the API returns a response object that contains a unique ID and the status of provisioning the load balancer.

In the response, the load balancer provisioning status is ACTIVE, PENDING_CREATE, or ERROR.

If the status is PENDING_CREATE, issue GET /lbaas/loadbalancers/loadbalancer_id to view the progress of the provisioning operation. When the load balancer status changes to ACTIVE, the load balancer is successfully provisioned and operational for traffic handling.

If the API cannot fulfill the request due to insufficient data or data that is not valid, the service returns the HTTP Bad Request (400) response code with information about the failure in the response body. Validation errors require that you correct the error and submit the request again.

You can configure all documented features of the load balancer at creation time by specifying the additional elements or attributes in the request.

Administrative users can specify a tenant ID that is different than their own to create load balancers for other tenants.

Example: Create a load balancer

  • tenant_id. Admin only. Required to create a load balancer for another tenant.
  • vip_subnet_id. The network on which to allocate the VIP address for the load balancer. A tenant can only create load balancer VIPs on networks that the policy authorizes, such as her own networks or shared or provider networks.

Some attributes receive default values if you omit them from the request:

  • admin_state_up. Default is true.
  • name. Default is an empty string.
  • description. Default is an empty string.

If the API cannot fulfill the request due to insufficient data or data that is not valid, the service returns the HTTP Bad Request (400) response code with information about the failure in the response body. Validation errors require that you correct the error and submit the request again.

You can configure all documented features of the load balancer at creation time by specifying the additional elements or attributes in the request.

Administrative users can specify a tenant ID that is different than their own to create load balancers for other tenants.

If you own the subnet where you want to create the load balancer VIP, you can specify a vip_address attribute. If you omit the vip_address attribute from the payload, the LBaaS service allocates a VIP address from the subnet of the load balancer VIP.

An optional flavor attribute can be passed to enable dynamic selection of an appropriate provider if configured by the operator. The basic selection algorithm chooses the provider in the first service profile currently associated with flavor.

You can also specify the provider attribute when you create a load balancer. You can set this attribute to any service provider with a LOADBALANCER service type. Setting both a flavor and a provider will result in a conflict error.

Example: Create a load balancer

Error response codes: 201,404,409,401,413,503,500

Request

Name In Type Description
description body string The human-readable description for the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
vip_address (Optional) body string The IP address of the VIP.
provider (Optional) body string The name of the provider.
vip_subnet_id body string The UUID of the subnet on which to allocate the virtual IP (VIP) address.
flavor body object A flavor object.
name body string Human-readable name of the resource.

Request Example

{
    "loadbalancer": {
        "name": "loadbalancer1",
        "description": "simple lb",
        "tenant_id": "b7c1a69e88bf4b21a8148f787aef2081",
        "vip_subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2",
        "vip_address": "10.0.0.4",
        "admin_state_up": true,
        "flavor": "a7ae5d5a-d855-4f9a-b187-af66b53f4d04"
    }
}

Response Parameters

Name In Type Description
description body string The human-readable description for the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
provisioning_status body string The provisioning status of the load balancer. This value is ACTIVE, PENDING_CREATE or ERROR.
listeners body array The associated listeners, if any.
vip_address (Optional) body string The IP address of the VIP.
operating_status body string The operating status of the load balancer. This value is ONLINE or OFFLINE.
provider (Optional) body string The name of the provider.
vip_subnet_id body string The UUID of the subnet on which to allocate the virtual IP (VIP) address.
flavor body object A flavor object.
id body string The UUID of the network.
loadbalancer body object A loadbalancer object.
name body string Human-readable name of the resource.
GET
/v2.0/lbaas/loadbalancers/{loadbalancer_id}

Show load balancer details

Shows details for a load balancer.

This operation returns a load balancer object, by ID. If you are not an administrative user and the load balancer object does not belong to your tenant account, the service returns the HTTP Forbidden (403) response code.

Normal response codes: 200

Error response codes: 404,403,500,401,413,503,409

Request

Response Parameters

Name In Type Description
description body string The human-readable description for the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
provisioning_status body string The provisioning status of the load balancer. This value is ACTIVE, PENDING_CREATE or ERROR.
listeners body array The associated listeners, if any.
vip_address (Optional) body string The IP address of the VIP.
operating_status body string The operating status of the load balancer. This value is ONLINE or OFFLINE.
provider (Optional) body string The name of the provider.
vip_subnet_id body string The UUID of the subnet on which to allocate the virtual IP (VIP) address.
flavor body object A flavor object.
id body string The UUID of the network.
loadbalancer body object A loadbalancer object.
name body string Human-readable name of the resource.

Response Example

{
    "loadbalancer": {
        "description": "simple lb",
        "admin_state_up": true,
        "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c",
        "provisioning_status": "ACTIVE",
        "listeners": [],
        "vip_address": "10.0.0.2",
        "vip_subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2",
        "id": "a9729389-6147-41a3-ab22-a24aed8692b2",
        "operating_status": "ONLINE",
        "name": "loadbalancer1"
    }
}
PUT
/v2.0/lbaas/loadbalancers/{loadbalancer_id}

Update load balancer

Updates a load balancer.

If the request is valid, the service returns the Accepted (202) response code. To confirm the update, check that the load balancer provisioning status is ACTIVE. If the status is PENDING_UPDATE, use a GET operation to poll the load balancer object for changes.

This operation returns the updated load balancer object with the ACTIVE, PENDING_UPDATE, or ERROR provisioning status.

Normal response codes: 200

Error response codes: 400,401,413,503,500

Request

Name In Type Description
name body string Human-readable name of the resource.
description body string The human-readable description for the resource.
loadbalancer body object A loadbalancer object.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).

Request Example

{
    "loadbalancer": {
        "admin_state_up": false,
        "description": "simple lb2",
        "name": "loadbalancer2"
    }
}

Response Parameters

Name In Type Description
description body string The human-readable description for the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
provisioning_status body string The provisioning status of the load balancer. This value is ACTIVE, PENDING_CREATE or ERROR.
listeners body array The associated listeners, if any.
vip_address (Optional) body string The IP address of the VIP.
operating_status body string The operating status of the load balancer. This value is ONLINE or OFFLINE.
provider (Optional) body string The name of the provider.
vip_subnet_id body string The UUID of the subnet on which to allocate the virtual IP (VIP) address.
flavor body object A flavor object.
id body string The UUID of the network.
loadbalancer body object A loadbalancer object.
name body string Human-readable name of the resource.

Response Example

{
    "loadbalancer": {
        "admin_state_up": false,
        "description": "simple lb2",
        "id": "a36c20d0-18e9-42ce-88fd-82a35977ee8c",
        "listeners": [],
        "name": "loadbalancer2",
        "operating_status": "ONLINE",
        "provisioning_status": "PENDING_UPDATE",
        "tenant_id": "b7c1a69e88bf4b21a8148f787aef2081",
        "vip_address": "10.0.0.4",
        "vip_subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2"
    }
}
DELETE
/v2.0/lbaas/loadbalancers/{loadbalancer_id}

Remove load balancer

Removes a load balancer and its associated configuration from the tenant account.

The API immediately purges any and all configuration data. You cannot recover it.

Example: Delete a load balancer

Error response codes: 204,400,401,413,503,500

Request

GET
/v2.0/lbaas/loadbalancers/{loadbalancer_id}/statuses

Show load balancer status tree

Shows the status tree for a load balancer.

This operation returns a status tree for a load balancer object, by load balancer ID. If you are not an administrative user and the load balancer object does not belong to the tenant account, the API returns the Forbidden (403) response code.

If the operation succeeds, the returned element is a status tree that contains the load balancer and all provisioning and operating statuses for its children.

Normal response codes: 200

Error response codes: 403,401,413,503,500

Request

Response Parameters

Name In Type Description
provisioning_status body string The provisioning status of the load balancer. This value is ACTIVE, PENDING_CREATE or ERROR.
listeners body array The associated listeners, if any.
healthmonitor body object The associated healthmonitor, if any.
members body array The list of members that belong to the pool.
pools body array List of pools that are associated with the health monitor.
id body string The UUID of the network.
operating_status body string The operating status of the load balancer. This value is ONLINE or OFFLINE.

Response Example

{
    "statuses": {
        "loadbalancer": {
            "name": "lb1",
            "listeners": [
                {
                    "pools": [
                        {
                            "name": "pool1",
                            "provisioning_status": "ACTIVE",
                            "health_monitor": {
                                "type": "HTTP",
                                "id": "90f7c765-0bc9-47c4-8513-4cc0c264c8f8",
                                "provisioning_status": "ACTIVE"
                            },
                            "members": [
                                {
                                    "address": "10.0.0.4",
                                    "protocol_port": 80,
                                    "id": "32723bee-2484-4de3-b6fc-c0b98d35fc84",
                                    "operating_status": "ONLINE",
                                    "provisioning_status": "ACTIVE"
                                },
                                {
                                    "address": "10.0.0.3",
                                    "protocol_port": 80,
                                    "id": "173b8164-0c9a-43ec-ab33-4ae0e7a8f863",
                                    "operating_status": "ONLINE",
                                    "provisioning_status": "ACTIVE"
                                }
                            ],
                            "id": "ae6f93b8-a3f6-46cd-bb18-c2ab0308abf7",
                            "operating_status": "ONLINE"
                        }
                    ],
                    "name": "listener1",
                    "id": "c2a41fbe-b70a-4645-bb11-4d3c28f23a25",
                    "operating_status": "ONLINE",
                    "provisioning_status": "ACTIVE"
                }
            ],
            "id": "a4c19566-6f81-4c96-ac11-33954a9825a2",
            "operating_status": "ONLINE",
            "provisioning_status": "ACTIVE"
        }
    }
}
GET
/v2.0/lbaas/listeners

List listeners

Lists all listeners.

This operation lists all listeners that are associated with your tenant account.

The list might be empty.

Example: List listeners

Normal response codes: 200

Error response codes: 500,401,503

Request

Response Parameters

Name In Type Description
protocol_port body integer The TCP or UDP port on which to listen.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
description body string The human-readable description for the resource.
default_tls_container_ref (Optional) body string A reference to a container of TLS secrets.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
loadbalancers body array A list of load balancer objects.
tenant_id body string The ID of the tenant who owns the resource.
sni_container_refs (Optional) body array A list of references to TLS secrets.
connection_limit (Optional) body integer The maximum number of connections permitted for this load balancer. Default is infinite.
listeners body array The associated listeners, if any.
default_pool_id (Optional) body string The UUID of default pool. Must have compatible protocol with listener.
id body string The UUID of the network.
name body string Human-readable name of the resource.

Response Example

{
    "listeners": [
        {
            "admin_state_up": true,
            "connection_limit": 100,
            "default_pool_id": null,
            "description": "",
            "id": "35cb8516-1173-4035-8dae-0dae3453f37f",
            "loadbalancers": [
                {
                    "id": "a9729389-6147-41a3-ab22-a24aed8692b2"
                }
            ],
            "name": "",
            "protocol": "HTTP",
            "protocol_port": 80,
            "tenant_id": "3e4d8bec50a845fcb09e03a4375c691d",
            "default_tls_container_ref": "https://barbican.endpoint/containers/a36c20d0-18e9-42ce-88fd-82a35977ee8c",
            "sni_container_refs": [
                "https://barbican.endpoint/containers/b36c20d0-18e9-42ce-88fd-82a35977ee8d",
                "https://barbican.endpoint/containers/c36c20d0-18e9-42ce-88fd-82a35977ee8e"
            ]
        }
    ]
}
POST
/v2.0/lbaas/listeners

Create listener

Creates a listener.

This operation provisions a new listener by using the configuration that you define in the request object. After the request is validated and the provisioning process begins, a response object is returned. The object contains a unique identifier.

At a minimum, you must specify these listener attributes:

  • tenant_id. Admin only. Required to create a listener for another tenant.
  • loadbalancer_id. The load balancer on which to provision this listener. A tenant can only create listeners on load balancers that the policy authorizes. For example, her own load balancers.
  • description. The load balancer description.
  • protocol. The protocol for which the front end listens. Must be HTTP, HTTPS, TCP, or TERMINATED_HTTPS.

Some attributes receive default values if you omit them from the request:

  • protocol_port. The port on which the front end listens. Must be an integer from 1 to 65535.
  • default_tls_container_ref. The reference to a container that holds TLS secrets. If you also specify sni_container_refs, this container is the default. This parameter is required for the TERMINATED_HTTPS protocol.
  • sni_container_refs. A list of references to containers that hold TLS secrets for server name indication (SNI). This parameter is required for the TERMINATED_HTTPS protocol.
  • admin_state_up. Default is true.
  • name. Default is an empty string.
  • description. Default is an empty string.
  • connection_limit. Default is -1, which indicates an infinite limit.

If the API cannot fulfill the request due to insufficient data or data that is not valid, the service returns the HTTP Bad Request (400) response code with information about the failure in the response body. Validation errors require that you correct the error and submit the request again.

You can configure all documented features of the listener at creation time by specifying the additional elements or attributes in the request.

Administrative users can specify a tenant ID that is different than their own to create listeners for other tenants.

To update a listener, the load balancer to which to attach must have an ACTIVE provisioning status.

Error response codes: 201,404,409,401,413,503,500

Request

Name In Type Description
protocol_port body integer The TCP or UDP port on which to listen.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
description body string The human-readable description for the resource.
default_tls_container_ref (Optional) body string A reference to a container of TLS secrets.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
sni_container_refs (Optional) body array A list of references to TLS secrets.
connection_limit (Optional) body integer The maximum number of connections permitted for this load balancer. Default is infinite.
listener body object A listener object.
default_pool_id (Optional) body string The UUID of default pool. Must have compatible protocol with listener.
loadbalancer_id body string The UUID of the load balancer.
name body string Human-readable name of the resource.

Request Example

{
    "listener": {
        "admin_state_up": true,
        "connection_limit": 100,
        "description": "listener one",
        "loadbalancer_id": "a36c20d0-18e9-42ce-88fd-82a35977ee8c",
        "name": "listener1",
        "protocol": "HTTP",
        "protocol_port": "80",
        "default_tls_container_ref": "https://barbican.endpoint/containers/a36c20d0-18e9-42ce-88fd-82a35977ee8c",
        "sni_container_refs": [
            "https://barbican.endpoint/containers/b36c20d0-18e9-42ce-88fd-82a35977ee8d",
            "https://barbican.endpoint/containers/c36c20d0-18e9-42ce-88fd-82a35977ee8e"
        ]
    }
}

Response Parameters

Name In Type Description
protocol_port body integer The TCP or UDP port on which to listen.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
description body string The human-readable description for the resource.
default_tls_container_ref (Optional) body string A reference to a container of TLS secrets.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
loadbalancers body array A list of load balancer objects.
tenant_id body string The ID of the tenant who owns the resource.
sni_container_refs (Optional) body array A list of references to TLS secrets.
connection_limit (Optional) body integer The maximum number of connections permitted for this load balancer. Default is infinite.
listener body object A listener object.
default_pool_id (Optional) body string The UUID of default pool. Must have compatible protocol with listener.
id body string The UUID of the network.
name body string Human-readable name of the resource.
GET
/v2.0/lbaas/listeners/{listener_id}

Show listener details

Shows details for a listener.

This operation returns a listener object, by ID. If you are not an administrative user and the listener object does not belong to your account, the API returns the HTTP Forbidden (403) response code.

Example: Show listener details

Normal response codes: 200

Error response codes: 404,403,500,401,413,503,409

Request

Response Parameters

Name In Type Description
protocol_port body integer The TCP or UDP port on which to listen.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
description body string The human-readable description for the resource.
default_tls_container_ref (Optional) body string A reference to a container of TLS secrets.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
loadbalancers body array A list of load balancer objects.
tenant_id body string The ID of the tenant who owns the resource.
sni_container_refs (Optional) body array A list of references to TLS secrets.
connection_limit (Optional) body integer The maximum number of connections permitted for this load balancer. Default is infinite.
listener body object A listener object.
default_pool_id (Optional) body string The UUID of default pool. Must have compatible protocol with listener.
id body string The UUID of the network.
name body string Human-readable name of the resource.

Response Example

{
    "listener": {
        "admin_state_up": true,
        "connection_limit": 100,
        "default_pool_id": null,
        "description": "",
        "id": "35cb8516-1173-4035-8dae-0dae3453f37f",
        "loadbalancers": [
            {
                "id": "a9729389-6147-41a3-ab22-a24aed8692b2"
            }
        ],
        "name": "",
        "protocol": "HTTP",
        "protocol_port": 80,
        "tenant_id": "3e4d8bec50a845fcb09e03a4375c691d",
        "default_tls_container_ref": "https://barbican.endpoint/containers/a36c20d0-18e9-42ce-88fd-82a35977ee8c",
        "sni_container_refs": [
            "https://barbican.endpoint/containers/b36c20d0-18e9-42ce-88fd-82a35977ee8d",
            "https://barbican.endpoint/containers/c36c20d0-18e9-42ce-88fd-82a35977ee8e"
        ]
    }
}
PUT
/v2.0/lbaas/listeners/{listener_id}

Update listener

Updates a listener.

This operation updates the attributes of a listener. Upon successful validation of the request, the service returns the HTTP Accepted (202) response code.

Note: You cannot update the listener_id, tenant_id, loadbalancer_id, loadbalancers, default_pool_id, protocol, and protocol_port attributes. Attempting to update an immutable attribute results in the HTTP Immutable (422) response code.

Note: You cannot update a listener if the load balancer to which the listener is attached does not have an ACTIVE provisioning status.

Normal response codes: 200

Error response codes: 400,401,413,503,500

Request

Name In Type Description
protocol_port body integer The TCP or UDP port on which to listen.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
description body string The human-readable description for the resource.
default_tls_container_ref (Optional) body string A reference to a container of TLS secrets.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
sni_container_refs (Optional) body array A list of references to TLS secrets.
connection_limit (Optional) body integer The maximum number of connections permitted for this load balancer. Default is infinite.
listener body object A listener object.
default_pool_id (Optional) body string The UUID of default pool. Must have compatible protocol with listener.
loadbalancer_id body string The UUID of the load balancer.
name body string Human-readable name of the resource.

Request Example

{
    "listener": {
        "admin_state_up": false,
        "connection_limit": 200,
        "description": "listener two",
        "name": "listener2",
        "default_tls_container_ref": "https://barbican.endpoint/containers/a36c20d0-18e9-42ce-88fd-82a35977ee8c",
        "sni_container_refs": [
            "https://barbican.endpoint/containers/b36c20d0-18e9-42ce-88fd-82a35977ee8d",
            "https://barbican.endpoint/containers/c36c20d0-18e9-42ce-88fd-82a35977ee8e"
        ]
    }
}

Response Parameters

Name In Type Description
protocol_port body integer The TCP or UDP port on which to listen.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
description body string The human-readable description for the resource.
default_tls_container_ref (Optional) body string A reference to a container of TLS secrets.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
loadbalancers body array A list of load balancer objects.
tenant_id body string The ID of the tenant who owns the resource.
sni_container_refs (Optional) body array A list of references to TLS secrets.
connection_limit (Optional) body integer The maximum number of connections permitted for this load balancer. Default is infinite.
listener body object A listener object.
default_pool_id (Optional) body string The UUID of default pool. Must have compatible protocol with listener.
id body string The UUID of the network.
name body string Human-readable name of the resource.

Response Example

{
    "listener": {
        "admin_state_up": false,
        "connection_limit": 200,
        "default_pool_id": null,
        "description": "listener two",
        "id": "39de4d56-d663-46e5-85a1-5b9d5fa17829",
        "loadbalancers": [
            {
                "id": "a36c20d0-18e9-42ce-88fd-82a35977ee8c"
            }
        ],
        "name": "listener2",
        "protocol": "HTTP",
        "protocol_port": 80,
        "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c",
        "default_tls_container_ref": "https://barbican.endpoint/containers/a36c20d0-18e9-42ce-88fd-82a35977ee8c",
        "sni_container_refs": [
            "https://barbican.endpoint/containers/b36c20d0-18e9-42ce-88fd-82a35977ee8d",
            "https://barbican.endpoint/containers/c36c20d0-18e9-42ce-88fd-82a35977ee8e"
        ]
    }
}
DELETE
/v2.0/lbaas/listeners/{listener_id}

Remove listener

Removes a listener.

This operation removes a listener and its associated configuration from the tenant account. The API immediately purges any and all configuration data. You cannot recover it.

You cannot delete a listener if the load balancer to which it is attached does not have an ACTIVE provisioning status.

Example: Delete a listener

Error response codes: 204,400,409,401,413,503,500

Request

GET
/v2.0/lbaas/pools

List pools

Lists all pools that are associated with your tenant account.

The list might be empty.

Example: List pools

Normal response codes: 200

Error response codes: 500,401,504

Request

Response Parameters

Name In Type Description
status body string The network status.
lb_method body string The load-balancer algorithm, which is round-robin (ROUND_ROBIN), least-connections (LEAST_CONNECTIONS), source IP (SOURCE_IP), and so on, that is used to distribute traffic to the pool members. This value, which must be supported, is dependent on the load-balancer provider. The round-robin algorithm must be supported.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
description body string The human-readable description for the resource.
health_monitors (Optional) body array List of health monitors that are associated with the pool.
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
tenant_id body string The ID of the tenant who owns the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
vip_id body string The UUID of the virtual IP (VIP) address.
members body array The list of members that belong to the pool.
pools body array List of pools that are associated with the health monitor.
id body string The UUID of the network.
name body string Human-readable name of the resource.

Response Example

{
    "pools": [
        {
            "status": "ACTIVE",
            "lb_algorithm": "ROUND_ROBIN",
            "protocol": "HTTP",
            "description": "",
            "health_monitors": [
                "b7633ade-24dc-4d72-8475-06aa22be5412"
            ],
            "members": [
                "cf024846-7516-4e3a-b0fb-6590322c836f"
            ],
            "status_description": null,
            "id": "5a9a3e9e-d1aa-448e-af37-a70171f2a332",
            "vip_id": "388c739a-6a57-4e74-bc7b-a5cd60248bba",
            "name": "pool1",
            "admin_state_up": true,
            "subnet_id": "aa547115-d710-4d6d-bb2c-b038d9c2704b",
            "tenant_id": "eabfefa3fd1740a88a47ad98e132d238",
            "health_monitors_status": [
                {
                    "monitor_id": "b7633ade-24dc-4d72-8475-06aa22be5412",
                    "status": "ACTIVE",
                    "status_description": null
                }
            ],
            "provider": "haproxy"
        }
    ]
}
POST
/v2.0/lbaas/pools

Create pool

Creates a pool.

This operation provisions a pool by using the configuration that you define in the request object. After the API validates the request and starts the provisioning process, the API returns a response object, which contains a unique ID.

At a minimum, you must specify these pool attributes:

  • tenant_id. Admin only. Required to create a pool for another tenant.
  • protocol. The protocol for which this pool and its members listen. A valid value is TCP, HTTP, or HTTPS.
  • lb_algorithm. The load-balancer algorithm, such as ROUND_ROBIN, LEAST_CONNECTIONS, and SOURCE_IP, that distributes traffic to the pool members. The load-balancer provider must support this algorithm.
  • listener_id. The UUID of the listener in which this pool becomes the default pool. Each listener has only one default pool.

Some attributes receive default values if you omit them from the request:

  • admin_state_up. Default is true.
  • name. Default is an empty string.
  • description. Default is an empty string.
  • session_persistence. Default is an empty dictionary.

If the API cannot fulfill the request due to insufficient data or data that is not valid, the service returns the HTTP Bad Request (400) response code with information about the failure in the response body. Validation errors require that you correct the error and submit the request again.

Users can configure all documented features at creation time by providing the additional elements or attributes in the request.

Administrative users can specify a tenant ID that is different than their own to create pools for other tenants.

To update a pool, the load balancer to which to attach must have an ACTIVE provisioning status.

Error response codes: 201,404,409,401,413,503,500

Request

Name In Type Description
lb_algorithm body string The load-balancer algorithm, which is round-robin (ROUND_ROBIN), least-connections (LEAST_CONNECTIONS), source IP (SOURCE_IP), and so on, that is used to distribute traffic to the pool members. This value, which must be supported, is dependent on the load-balancer provider. The round-robin algorithm must be supported.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
description body string The human-readable description for the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
tenant_id body string The ID of the tenant who owns the resource.
listener_id (Optional) body string The UUID of the listener.
name body string Human-readable name of the resource.

Request Example

{
    "pool": {
        "admin_state_up": true,
        "description": "simple pool",
        "lb_algorithm": "ROUND_ROBIN",
        "name": "my-pool",
        "protocol": "HTTP",
        "subnet_id": "e301aed0-d9e7-498a-977c-1bbfaf14ed5d"
    }
}

Response Parameters

Name In Type Description
lb_algorithm body string The load-balancer algorithm, which is round-robin (ROUND_ROBIN), least-connections (LEAST_CONNECTIONS), source IP (SOURCE_IP), and so on, that is used to distribute traffic to the pool members. This value, which must be supported, is dependent on the load-balancer provider. The round-robin algorithm must be supported.
status body string The network status.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
description body string The human-readable description for the resource.
vip_id body string The UUID of the virtual IP (VIP) address.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
tenant_id body string The ID of the tenant who owns the resource.
session_persistence (Optional) body object The session persistence algorithm. This algorithm is a dictionary with type and cookie_name keys.
healthmonitor_id (Optional) body string The UUID of the health monitor.
health_monitors_status body string The statuses of the health monitors that are associated with the pool.
members body array The list of members that belong to the pool.
id body string The UUID of the network.
pool body object A pool object.
name body string Human-readable name of the resource.
GET
/v2.0/lbaas/pools/{pool_id}

Show pool details

Shows details for a pool.

This operation shows details for a pool, by ID. If you are not an administrative user and the pool object does not belong to your tenant account, the call returns the HTTP Forbidden (403) response code.

If this operation succeeds, it returns a pool element.

Example: Show pool details

Normal response codes: 200

Error response codes: 404,403,500,401,413,503,409

Request

Response Parameters

Name In Type Description
status body string The network status.
lb_method body string The load-balancer algorithm, which is round-robin (ROUND_ROBIN), least-connections (LEAST_CONNECTIONS), source IP (SOURCE_IP), and so on, that is used to distribute traffic to the pool members. This value, which must be supported, is dependent on the load-balancer provider. The round-robin algorithm must be supported.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
description body string The human-readable description for the resource.
health_monitors (Optional) body array List of health monitors that are associated with the pool.
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
tenant_id body string The ID of the tenant who owns the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
vip_id body string The UUID of the virtual IP (VIP) address.
members body array The list of members that belong to the pool.
pools body array List of pools that are associated with the health monitor.
id body string The UUID of the network.
name body string Human-readable name of the resource.

Response Example

{
    "pool": {
        "status": "ACTIVE",
        "lb_algorithm": "ROUND_ROBIN",
        "protocol": "HTTP",
        "description": "",
        "health_monitors": [
            "b7633ade-24dc-4d72-8475-06aa22be5412"
        ],
        "members": [
            "cf024846-7516-4e3a-b0fb-6590322c836f"
        ],
        "status_description": null,
        "id": "5a9a3e9e-d1aa-448e-af37-a70171f2a332",
        "vip_id": "388c739a-6a57-4e74-bc7b-a5cd60248bba",
        "name": "pool1",
        "admin_state_up": true,
        "subnet_id": "aa547115-d710-4d6d-bb2c-b038d9c2704b",
        "tenant_id": "eabfefa3fd1740a88a47ad98e132d238",
        "health_monitors_status": [
            {
                "monitor_id": "b7633ade-24dc-4d72-8475-06aa22be5412",
                "status": "ACTIVE",
                "status_description": null
            }
        ],
        "provider": "haproxy"
    }
}
PUT
/v2.0/lbaas/pools/{pool_id}

Update pool

Updates a pool.

This operation updates the attributes of a pool. Upon successful validation of the request, the service returns the HTTP Accepted (202) response code.

Note: You cannot update the pool UUID, tenant_id, listener_id, listeners, health_monitor_id, protocol, and members immutable attributes. If you try to update any of these attributes, the service returns the HTTP Immutable (422) response code.

Note: You cannot update a pool if the load balancer to which it is attached does not have an ACTIVE provisioning status.

Normal response codes: 200

Error response codes: 400,401,413,503,500

Request

Name In Type Description
pool body object A pool object.
lb_method body string The load-balancer algorithm, which is round-robin (ROUND_ROBIN), least-connections (LEAST_CONNECTIONS), source IP (SOURCE_IP), and so on, that is used to distribute traffic to the pool members. This value, which must be supported, is dependent on the load-balancer provider. The round-robin algorithm must be supported.
description body string The human-readable description for the resource.
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).

Request Example

{
    "pool": {
        "name": "SuperPool"
    }
}

Response Parameters

Name In Type Description
status body string The network status.
lb_method body string The load-balancer algorithm, which is round-robin (ROUND_ROBIN), least-connections (LEAST_CONNECTIONS), source IP (SOURCE_IP), and so on, that is used to distribute traffic to the pool members. This value, which must be supported, is dependent on the load-balancer provider. The round-robin algorithm must be supported.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
description body string The human-readable description for the resource.
health_monitors (Optional) body array List of health monitors that are associated with the pool.
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
tenant_id body string The ID of the tenant who owns the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
vip_id body string The UUID of the virtual IP (VIP) address.
members body array The list of members that belong to the pool.
pools body array List of pools that are associated with the health monitor.
id body string The UUID of the network.
name body string Human-readable name of the resource.

Response Example

{
    "pool": {
        "status": "PENDING_UPDATE",
        "lb_algorithm": "ROUND_ROBIN",
        "protocol": "HTTP",
        "description": "",
        "health_monitors": [
            "b7633ade-24dc-4d72-8475-06aa22be5412"
        ],
        "members": [
            "cf024846-7516-4e3a-b0fb-6590322c836f"
        ],
        "status_description": null,
        "id": "5a9a3e9e-d1aa-448e-af37-a70171f2a332",
        "vip_id": "388c739a-6a57-4e74-bc7b-a5cd60248bba",
        "name": "SuperPool",
        "admin_state_up": true,
        "subnet_id": "aa547115-d710-4d6d-bb2c-b038d9c2704b",
        "tenant_id": "eabfefa3fd1740a88a47ad98e132d238",
        "health_monitors_status": [
            {
                "monitor_id": "b7633ade-24dc-4d72-8475-06aa22be5412",
                "status": "ACTIVE",
                "status_description": null
            }
        ],
        "provider": "haproxy"
    }
}
DELETE
/v2.0/lbaas/pools/{pool_id}

Remove pool

Removes a pool.

This operation removes a pool and its associated configuration from the tenant account. The API immediately purges any and all configuration data. You cannot recover it.

You cannot delete a pool if the load balancer to which it is attached does not have an ACTIVE provisioning status.

Error response codes: 204,400,409,401,413,503,500

Request

GET
/v2.0/lbaas/pools/{pool_id}/members

List pool members

Lists members of a pool.

Lists all members that are associated with a pool that is associated with your tenant account. The list of members includes only members that belong to the pool object identified by pool_id.

The list might be empty.

Example: List pool members

Normal response codes: 200

Error response codes: 500,401,503

Request

Response Parameters

Name In Type Description
status body string The network status.
status_description body string Human-readable description of the status.
weight (Optional) body integer A positive integer value that indicates the relative portion of traffic that this member should receive from the pool. For example, a member with a weight of 10 receives five times as much traffic as a member with a weight of 2.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
pool_id (Optional) path string The UUID for the pool.
members body array The list of members that belong to the pool.
address body string The IP address of the member.
protocol_port body integer The TCP or UDP port on which to listen.
id body string The UUID of the network.

Response Example

{
    "members": [
        {
            "address": "10.0.0.8",
            "admin_state_up": true,
            "id": "9a7aff27-fd41-4ec1-ba4c-3eb92c629313",
            "protocol_port": 80,
            "subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2",
            "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c",
            "weight": 1
        }
    ]
}
POST
/v2.0/lbaas/pools/{pool_id}/members

Add member to pool

Adds a member to a pool.

This operation provisions a member and adds it to a pool by using the configuration that you define in the request object. After the API validates the request and starts the provisioning process, it returns a response object, which contains a unique ID.

At a minimum, you must specify these pool attributes:

  • tenant_id. Admin only. Required to create a pool for another tenant.
  • address. The IP address of the member to receive traffic from the load balancer.
  • protocol_port The port on which the member listens for traffic.

Some attributes receive default values if you omit them from the request:

  • admin_state_up. Default is true.
  • weight. Default is 1.

If you omit the subnet_id parameter, LBaaS uses the vip_subnet_id parameter value for the subnet UUID.

If the request fails due to incorrect data, the service returns the HTTP Bad Request (400) response code with information about the failure in the response body. Validation errors require that you correct the error and submit the request again.

To configure all documented member features at creation time, specify additional elements or attributes in the request.

Administrative users can specify a tenant ID that is different than their own to create members for other tenants.

To update a member, the load balancer must have an ACTIVE provisioning status.

Error response codes: 201,404,409,401,413,503,500

Request

Name In Type Description
member body object A member object.
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
protocol_port body integer The TCP or UDP port on which to listen.
tenant_id body string The ID of the tenant who owns the resource.
address body string The IP address of the member.

Request Example

{
    "member": {
        "address": "10.0.0.22",
        "admin_state_up": true,
        "protocol_port": "90",
        "pool_id": "5a9a3e9e-d1aa-448e-af37-a70171f2a332",
        "weight": "1"
    }
}

Response Parameters

Name In Type Description
status body string The network status.
weight (Optional) body integer A positive integer value that indicates the relative portion of traffic that this member should receive from the pool. For example, a member with a weight of 10 receives five times as much traffic as a member with a weight of 2.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
tenant_id body string The ID of the tenant who owns the resource.
member body object A member object.
address body string The IP address of the member.
protocol_port body integer The TCP or UDP port on which to listen.
id body string The UUID of the network.
GET
/v2.0/lbaas/pools/{pool_id}/members/{member_id}

Show pool member details

Shows details for a pool member.

This operation returns a member object identified by member_id that belongs to a pool object identified by pool_id. If you are not an administrative user and the pool or member object does not belong to your tenant account, the service returns the HTTP Forbidden (403) response code.

If this operation succeeds, it returns a pool element.

Example: Show pool member details

Normal response codes: 200

Error response codes: 404,403,500,401,413,503,409

Request

Response Parameters

Name In Type Description
status body string The network status.
status_description body string Human-readable description of the status.
weight (Optional) body integer A positive integer value that indicates the relative portion of traffic that this member should receive from the pool. For example, a member with a weight of 10 receives five times as much traffic as a member with a weight of 2.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
pool_id (Optional) path string The UUID for the pool.
member body object A member object.
address body string The IP address of the member.
protocol_port body integer The TCP or UDP port on which to listen.
id body string The UUID of the network.

Response Example

{
    "member": {
        "admin_state_up": true,
        "status": "ACTIVE",
        "status_description": null,
        "weight": 1,
        "address": "10.0.1.22",
        "tenant_id": "eabfefa3fd1740a88a47ad98e132d238",
        "protocol_port": 90,
        "id": "cf024846-7516-4e3a-b0fb-6590322c836f",
        "pool_id": "5a9a3e9e-d1aa-448e-af37-a70171f2a332"
    }
}
PUT
/v2.0/lbaas/pools/{pool_id}/members/{member_id}

Update pool member

Updates attributes for a pool member.

Upon successful validation of the request, the service returns the HTTP OK (200) response code.

Note: You cannot update the member UUID, tenant_id, address, protocol_port, and subnet_id attributes. If you attempt to update any of these attributes, the service returns the HTTP Immutable (422) response code.

Note: You cannot update a member if the attached load balancer does not have an ACTIVE provisioning status.

Normal response codes: 200

Error response codes: 400,401,413,503,500

Request

Name In Type Description
member body object A member object.
pool_id (Optional) path string The UUID for the pool.
weight (Optional) body integer A positive integer value that indicates the relative portion of traffic that this member should receive from the pool. For example, a member with a weight of 10 receives five times as much traffic as a member with a weight of 2.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).

Request Example

{
    "member": {
        "weight": 5
    }
}

Response Parameters

Name In Type Description
status body string The network status.
status_description body string Human-readable description of the status.
weight (Optional) body integer A positive integer value that indicates the relative portion of traffic that this member should receive from the pool. For example, a member with a weight of 10 receives five times as much traffic as a member with a weight of 2.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
pool_id (Optional) path string The UUID for the pool.
member body object A member object.
address body string The IP address of the member.
protocol_port body integer The TCP or UDP port on which to listen.
id body string The UUID of the network.

Response Example

{
    "member": {
        "admin_state_up": true,
        "status": "PENDING_UPDATE",
        "status_description": null,
        "weight": 5,
        "address": "10.0.1.22",
        "tenant_id": "eabfefa3fd1740a88a47ad98e132d238",
        "protocol_port": 90,
        "id": "cf024846-7516-4e3a-b0fb-6590322c836f",
        "pool_id": "5a9a3e9e-d1aa-448e-af37-a70171f2a332"
    }
}
DELETE
/v2.0/lbaas/pools/{pool_id}/members/{member_id}

Remove member from pool

Removes a member from a pool and its associated configuration from the tenant account.

The API immediately purges any and all configuration data. You cannot recover it.

You cannot delete a member if the attached load balancer does not have an ACTIVE provisioning status.

Example: Remove a member from a pool

Error response codes: 204,400,409,401,413,503,500

Request

GET
/v2.0/lbaas/health_monitors

List health monitors

Lists health monitors.

This operation lists all health monitors that are associated with your tenant account.

This operation returns a list, which might be empty.

Normal response codes: 200

Error response codes: 500,401,503

Request

Response Parameters

Name In Type Description
health_monitors (Optional) body array List of health monitors that are associated with the pool.
tenant_id body string The ID of the tenant who owns the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
delay body integer The time, in seconds, between sending probes to members.
expected_codes (Optional) body string The list of HTTP status codes expected in response from the member to declare it healthy. Specify one of the following values: - A single value, such as 200. - A list, such as 200, 202. - A range, such as 200-204.
max_retries body integer The number of allowed connection failures before changing the status of the member to INACTIVE. A valid value is from 1 to 10.
http_method (Optional) body string The HTTP method that the monitor uses for requests.
timeout body integer The maximum time, in seconds, that a monitor waits to connect before it times out. This value must be less than the delay value.
pools body array List of pools that are associated with the health monitor.
url_path (Optional) body string The HTTP path of the request sent by the monitor to test the health of a member. A valid value is a string that begins with a forward slash (/).
type body string The type of probe sent by the load balancer to verify the member state. A valid value is PING, TCP, HTTP, or HTTPS.
id body string The UUID of the network.

Response Example

{
    "health_monitors": [
        {
            "admin_state_up": true,
            "tenant_id": "eabfefa3fd1740a88a47ad98e132d238",
            "delay": 1,
            "expected_codes": "200,201,202",
            "max_retries": 5,
            "http_method": "GET",
            "timeout": 1,
            "pools": [
                {
                    "status": "ACTIVE",
                    "status_description": null,
                    "pool_id": "5a9a3e9e-d1aa-448e-af37-a70171f2a332"
                }
            ],
            "url_path": "/index.html",
            "type": "HTTP",
            "id": "b7633ade-24dc-4d72-8475-06aa22be5412"
        }
    ]
}
POST
/v2.0/lbaas/health_monitors

Create health monitor

Creates a health monitor.

This operation provisions a health monitor by using the configuration that you define in the request object. After the API validates the request and start the provisioning process, it returns a response object. The object contains a unique identifier.

At a minimum, you must specify these health monitor attributes:

  • tenant_id. Admin only. Required to create a health monitor for another tenant.
  • type. The type of health monitor. A valid value is TCP, HTTP, or HTTPS.
  • delay. The interval, in seconds, between health checks.
  • timeout. The time, in seconds, after which a health check times out.
  • max_retries. Number of failed health checks before marked as OFFLINE.
  • pool_id. The pool to monitor.

Some attributes receive default values if you omit them from the request, and are only useful when you specify a health monitor type of HTTP(S):

  • http_method. Default is GET.
  • url_path. Default is /.
  • expected_codes. The expected HTTP status codes to get from a successful health check. Default is 200.
  • admin_state_up. Default is true.

If the API cannot fulfill the request due to insufficient data or data that is not valid, it returns the Bad Request (400) response code with information about the nature of the failure in the response body. Failures in the validation process are non- recoverable and require that you correct the cause of the failure and submit the request again.

You can configure all documented features of the health monitor at creation time by specifying the additional elements or attributes in the request.

Administrative users can specify a tenant ID that is different than their own to create health monitors for other tenants.

To update a health monitor, the load balancer to which to attach must have an ACTIVE provisioning status.

Error response codes: 201,404,409,401,413,503,500

Request

Name In Type Description
health_monitor body object A health_monitor object.
tenant_id body string The ID of the tenant who owns the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
delay body integer The time, in seconds, between sending probes to members.
expected_codes (Optional) body string The list of HTTP status codes expected in response from the member to declare it healthy. Specify one of the following values: - A single value, such as 200. - A list, such as 200, 202. - A range, such as 200-204.
max_retries body integer The number of allowed connection failures before changing the status of the member to INACTIVE. A valid value is from 1 to 10.
http_method (Optional) body string The HTTP method that the monitor uses for requests.
timeout body integer The maximum time, in seconds, that a monitor waits to connect before it times out. This value must be less than the delay value.
url_path (Optional) body string The HTTP path of the request sent by the monitor to test the health of a member. A valid value is a string that begins with a forward slash (/).
type body string The type of probe sent by the load balancer to verify the member state. A valid value is PING, TCP, HTTP, or HTTPS.

Request Example

{
    "health_monitor": {
        "admin_state_up": true,
        "delay": "1",
        "expected_codes": "200,201,202",
        "http_method": "GET",
        "max_retries": 5,
        "timeout": 1,
        "type": "HTTP",
        "url_path": "/index.html"
    }
}

Response Parameters

Name In Type Description
health_monitor body object A health_monitor object.
tenant_id body string The ID of the tenant who owns the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
delay body integer The time, in seconds, between sending probes to members.
expected_codes (Optional) body string The list of HTTP status codes expected in response from the member to declare it healthy. Specify one of the following values: - A single value, such as 200. - A list, such as 200, 202. - A range, such as 200-204.
max_retries body integer The number of allowed connection failures before changing the status of the member to INACTIVE. A valid value is from 1 to 10.
http_method (Optional) body string The HTTP method that the monitor uses for requests.
timeout body integer The maximum time, in seconds, that a monitor waits to connect before it times out. This value must be less than the delay value.
pools body array List of pools that are associated with the health monitor.
url_path (Optional) body string The HTTP path of the request sent by the monitor to test the health of a member. A valid value is a string that begins with a forward slash (/).
type body string The type of probe sent by the load balancer to verify the member state. A valid value is PING, TCP, HTTP, or HTTPS.
id body string The UUID of the network.
GET
/v2.0/lbaas/health_monitors/{health_monitor_id}

Show health monitor details

Shows details for a health monitor.

This operation returns a health monitor object, by health monitor ID. If you are not an administrative user and the health monitor object does not belong to your tenant account, the service returns the HTTP Forbidden (403) response code.

Example: Show health monitor details

Normal response codes: 200

Error response codes: 404,403,500,401,413,503,409

Request

Response Parameters

Name In Type Description
health_monitor body object A health_monitor object.
tenant_id body string The ID of the tenant who owns the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
delay body integer The time, in seconds, between sending probes to members.
expected_codes (Optional) body string The list of HTTP status codes expected in response from the member to declare it healthy. Specify one of the following values: - A single value, such as 200. - A list, such as 200, 202. - A range, such as 200-204.
max_retries body integer The number of allowed connection failures before changing the status of the member to INACTIVE. A valid value is from 1 to 10.
http_method (Optional) body string The HTTP method that the monitor uses for requests.
timeout body integer The maximum time, in seconds, that a monitor waits to connect before it times out. This value must be less than the delay value.
pools body array List of pools that are associated with the health monitor.
url_path (Optional) body string The HTTP path of the request sent by the monitor to test the health of a member. A valid value is a string that begins with a forward slash (/).
type body string The type of probe sent by the load balancer to verify the member state. A valid value is PING, TCP, HTTP, or HTTPS.
id body string The UUID of the network.

Response Example

{
    "health_monitor": {
        "admin_state_up": true,
        "tenant_id": "eabfefa3fd1740a88a47ad98e132d238",
        "delay": 1,
        "expected_codes": "200,201,202",
        "max_retries": 5,
        "http_method": "GET",
        "timeout": 1,
        "pools": [
            {
                "status": "ACTIVE",
                "status_description": null,
                "pool_id": "5a9a3e9e-d1aa-448e-af37-a70171f2a332"
            }
        ],
        "url_path": "/index.html",
        "type": "HTTP",
        "id": "b7633ade-24dc-4d72-8475-06aa22be5412"
    }
}
PUT
/v2.0/lbaas/health_monitors/{health_monitor_id}

Update health monitor

Updates a health monitor.

Upon successful validation of the request, the service returns the HTTP Accepted (202) response code.

Note: The health monitor UUID, tenant_id, pool_id, and type are immutable attributes and cannot be updated. If you specify an unsupported attribute, the service returns the HTTP Immutable (422) response code.

Normal response codes: 200

Error response codes: 400,401,413,503,500

Request

Name In Type Description
health_monitor body object A health_monitor object.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
delay body integer The time, in seconds, between sending probes to members.
expected_codes (Optional) body string The list of HTTP status codes expected in response from the member to declare it healthy. Specify one of the following values: - A single value, such as 200. - A list, such as 200, 202. - A range, such as 200-204.
max_retries body integer The number of allowed connection failures before changing the status of the member to INACTIVE. A valid value is from 1 to 10.
http_method (Optional) body string The HTTP method that the monitor uses for requests.
timeout body integer The maximum time, in seconds, that a monitor waits to connect before it times out. This value must be less than the delay value.
url_path (Optional) body string The HTTP path of the request sent by the monitor to test the health of a member. A valid value is a string that begins with a forward slash (/).

Request Example

{
    "health_monitor": {
        "admin_state_up": false,
        "delay": "2",
        "expected_codes": "200",
        "http_method": "POST",
        "max_retries": 2,
        "timeout": 2,
        "url_path": "/page.html"
    }
}

Response Parameters

Name In Type Description
health_monitor body object A health_monitor object.
tenant_id body string The ID of the tenant who owns the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
delay body integer The time, in seconds, between sending probes to members.
expected_codes (Optional) body string The list of HTTP status codes expected in response from the member to declare it healthy. Specify one of the following values: - A single value, such as 200. - A list, such as 200, 202. - A range, such as 200-204.
max_retries body integer The number of allowed connection failures before changing the status of the member to INACTIVE. A valid value is from 1 to 10.
http_method (Optional) body string The HTTP method that the monitor uses for requests.
timeout body integer The maximum time, in seconds, that a monitor waits to connect before it times out. This value must be less than the delay value.
pools body array List of pools that are associated with the health monitor.
url_path (Optional) body string The HTTP path of the request sent by the monitor to test the health of a member. A valid value is a string that begins with a forward slash (/).
type body string The type of probe sent by the load balancer to verify the member state. A valid value is PING, TCP, HTTP, or HTTPS.
id body string The UUID of the network.

Response Example

{
    "health_monitor": {
        "admin_state_up": false,
        "tenant_id": "eabfefa3fd1740a88a47ad98e132d238",
        "delay": 2,
        "expected_codes": "200",
        "max_retries": 2,
        "http_method": "POST",
        "timeout": 2,
        "pools": [
            {
                "status": "ACTIVE",
                "status_description": null,
                "pool_id": "5a9a3e9e-d1aa-448e-af37-a70171f2a332"
            }
        ],
        "url_path": "/page.html",
        "type": "HTTP",
        "id": "b7633ade-24dc-4d72-8475-06aa22be5412"
    }
}
DELETE
/v2.0/lbaas/health_monitors/{health_monitor_id}

Remove health monitor

Removes a health monitor and its associated configuration from the tenant account.

The API immediately purges any and all configuration data. You cannot recover it.

You cannot delete a health monitor if the attached load balancer does not have an ACTIVE provisioning status.

Example: Delete a health monitor

Error response codes: 204,400,409,401,413,503,500

Request

LBaaS 1.0 (DEPRECATED)

The Load-Balancer-as-a-Service (LBaaS) v1.0 extension pairs with the Networking v2.0 API to enable OpenStack tenants to manage load balancers for their VMs. With this extension, you can load-balance client traffic from one network to application services, such as VMs, on the same network.

Use this extension to create and manage virtual IP addresses (VIPs), pools, members of a pool, health monitors, and view status of a resource.

Note

LBaaS 1.0 support was removed in Newton release. It’s no longer available in any installations starting from this release.

Load balancer statuses

Status Description
ACTIVE The resource is ready and active.
PENDING_CREATE The resource is being created.
PENDING_UPDATE The resource is being updated.
PENDING_DELETE The resource is pending deletion.
INACTIVE The resource is not active.
ERROR An object within the service is not working. The error_details attribute provides an explanation for the error, its cause, and possibly a solution.
GET
/v2.0/lb/pools

List pools

Lists pools.

Normal response codes: 200 Error response codes:400,401,413,503,500,

Request

Response Parameters

Name In Type Description
lb_algorithm body string The load-balancer algorithm, which is round-robin (ROUND_ROBIN), least-connections (LEAST_CONNECTIONS), source IP (SOURCE_IP), and so on, that is used to distribute traffic to the pool members. This value, which must be supported, is dependent on the load-balancer provider. The round-robin algorithm must be supported.
status body string The network status.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
description body string The human-readable description for the resource.
health_monitors (Optional) body array List of health monitors that are associated with the pool.
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
tenant_id body string The ID of the tenant who owns the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
vip_id body string The UUID of the virtual IP (VIP) address.
health_monitors_status body string The statuses of the health monitors that are associated with the pool.
members body array The list of members that belong to the pool.
provider (Optional) body string The name of the provider.
pools body array List of pools that are associated with the health monitor.
status_description body string Human-readable description of the status.
id body string The UUID of the network.
name body string Human-readable name of the resource.

Response Example

{
    "pools": [
        {
            "status": "ACTIVE",
            "lb_algorithm": "ROUND_ROBIN",
            "protocol": "HTTP",
            "description": "",
            "health_monitors": [
                "b7633ade-24dc-4d72-8475-06aa22be5412"
            ],
            "members": [
                "cf024846-7516-4e3a-b0fb-6590322c836f"
            ],
            "status_description": null,
            "id": "5a9a3e9e-d1aa-448e-af37-a70171f2a332",
            "vip_id": "388c739a-6a57-4e74-bc7b-a5cd60248bba",
            "name": "pool1",
            "admin_state_up": true,
            "subnet_id": "aa547115-d710-4d6d-bb2c-b038d9c2704b",
            "tenant_id": "eabfefa3fd1740a88a47ad98e132d238",
            "health_monitors_status": [
                {
                    "monitor_id": "b7633ade-24dc-4d72-8475-06aa22be5412",
                    "status": "ACTIVE",
                    "status_description": null
                }
            ],
            "provider": "haproxy"
        }
    ]
}
POST
/v2.0/lb/pools

Create a load balancer pool

Creates a load balancer pool.

Error response codes:201,400,401,413,503,500,

Request

Name In Type Description
lb_method body string The load-balancer algorithm, which is round-robin (ROUND_ROBIN), least-connections (LEAST_CONNECTIONS), source IP (SOURCE_IP), and so on, that is used to distribute traffic to the pool members. This value, which must be supported, is dependent on the load-balancer provider. The round-robin algorithm must be supported.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
description body string The human-readable description for the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
tenant_id body string The ID of the tenant who owns the resource.
pool body object A pool object.
name body string Human-readable name of the resource.

Request Example

{
    "pool": {
        "admin_state_up": true,
        "description": "simple pool",
        "lb_algorithm": "ROUND_ROBIN",
        "name": "my-pool",
        "protocol": "HTTP",
        "subnet_id": "e301aed0-d9e7-498a-977c-1bbfaf14ed5d"
    }
}

Response Parameters

Name In Type Description
lb_algorithm body string The load-balancer algorithm, which is round-robin (ROUND_ROBIN), least-connections (LEAST_CONNECTIONS), source IP (SOURCE_IP), and so on, that is used to distribute traffic to the pool members. This value, which must be supported, is dependent on the load-balancer provider. The round-robin algorithm must be supported.
status body string The network status.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
description body string The human-readable description for the resource.
health_monitors (Optional) body array List of health monitors that are associated with the pool.
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
tenant_id body string The ID of the tenant who owns the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
vip_id body string The UUID of the virtual IP (VIP) address.
health_monitors_status body string The statuses of the health monitors that are associated with the pool.
members body array The list of members that belong to the pool.
provider (Optional) body string The name of the provider.
status_description body string Human-readable description of the status.
id body string The UUID of the network.
pool body object A pool object.
name body string Human-readable name of the resource.
GET
/v2.0/lb/pools/{pool_id}

Show pool details

Shows details for a pool.

Normal response codes: 200 Error response codes:400,401,413,503,500,

Request

Name In Type Description
pool_id (Optional) path string The UUID for the pool.

Response Parameters

Name In Type Description
lb_algorithm body string The load-balancer algorithm, which is round-robin (ROUND_ROBIN), least-connections (LEAST_CONNECTIONS), source IP (SOURCE_IP), and so on, that is used to distribute traffic to the pool members. This value, which must be supported, is dependent on the load-balancer provider. The round-robin algorithm must be supported.
status body string The network status.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
description body string The human-readable description for the resource.
health_monitors (Optional) body array List of health monitors that are associated with the pool.
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
tenant_id body string The ID of the tenant who owns the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
vip_id body string The UUID of the virtual IP (VIP) address.
health_monitors_status body string The statuses of the health monitors that are associated with the pool.
members body array The list of members that belong to the pool.
provider (Optional) body string The name of the provider.
status_description body string Human-readable description of the status.
id body string The UUID of the network.
pool body object A pool object.
name body string Human-readable name of the resource.

Response Example

{
    "pool": {
        "status": "ACTIVE",
        "lb_algorithm": "ROUND_ROBIN",
        "protocol": "HTTP",
        "description": "",
        "health_monitors": [
            "b7633ade-24dc-4d72-8475-06aa22be5412"
        ],
        "members": [
            "cf024846-7516-4e3a-b0fb-6590322c836f"
        ],
        "status_description": null,
        "id": "5a9a3e9e-d1aa-448e-af37-a70171f2a332",
        "vip_id": "388c739a-6a57-4e74-bc7b-a5cd60248bba",
        "name": "pool1",
        "admin_state_up": true,
        "subnet_id": "aa547115-d710-4d6d-bb2c-b038d9c2704b",
        "tenant_id": "eabfefa3fd1740a88a47ad98e132d238",
        "health_monitors_status": [
            {
                "monitor_id": "b7633ade-24dc-4d72-8475-06aa22be5412",
                "status": "ACTIVE",
                "status_description": null
            }
        ],
        "provider": "haproxy"
    }
}
PUT
/v2.0/lb/pools/{pool_id}

Update pool

Updates a load balancer pool.

Normal response codes: 200 Error response codes:400,401,413,503,500,

Request

Name In Type Description
pool body object A pool object.
lb_method body string The load-balancer algorithm, which is round-robin (ROUND_ROBIN), least-connections (LEAST_CONNECTIONS), source IP (SOURCE_IP), and so on, that is used to distribute traffic to the pool members. This value, which must be supported, is dependent on the load-balancer provider. The round-robin algorithm must be supported.
description body string The human-readable description for the resource.
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).
pool_id (Optional) path string The UUID for the pool.

Request Example

{
    "pool": {
        "name": "SuperPool"
    }
}

Response Parameters

Name In Type Description
lb_algorithm body string The load-balancer algorithm, which is round-robin (ROUND_ROBIN), least-connections (LEAST_CONNECTIONS), source IP (SOURCE_IP), and so on, that is used to distribute traffic to the pool members. This value, which must be supported, is dependent on the load-balancer provider. The round-robin algorithm must be supported.
status body string The network status.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
description body string The human-readable description for the resource.
health_monitors (Optional) body array List of health monitors that are associated with the pool.
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
tenant_id body string The ID of the tenant who owns the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
vip_id body string The UUID of the virtual IP (VIP) address.
health_monitors_status body string The statuses of the health monitors that are associated with the pool.
members body array The list of members that belong to the pool.
provider (Optional) body string The name of the provider.
status_description body string Human-readable description of the status.
id body string The UUID of the network.
pool body object A pool object.
name body string Human-readable name of the resource.

Response Example

{
    "pool": {
        "status": "PENDING_UPDATE",
        "lb_algorithm": "ROUND_ROBIN",
        "protocol": "HTTP",
        "description": "",
        "health_monitors": [
            "b7633ade-24dc-4d72-8475-06aa22be5412"
        ],
        "members": [
            "cf024846-7516-4e3a-b0fb-6590322c836f"
        ],
        "status_description": null,
        "id": "5a9a3e9e-d1aa-448e-af37-a70171f2a332",
        "vip_id": "388c739a-6a57-4e74-bc7b-a5cd60248bba",
        "name": "SuperPool",
        "admin_state_up": true,
        "subnet_id": "aa547115-d710-4d6d-bb2c-b038d9c2704b",
        "tenant_id": "eabfefa3fd1740a88a47ad98e132d238",
        "health_monitors_status": [
            {
                "monitor_id": "b7633ade-24dc-4d72-8475-06aa22be5412",
                "status": "ACTIVE",
                "status_description": null
            }
        ],
        "provider": "haproxy"
    }
}
DELETE
/v2.0/lb/pools/{pool_id}

Delete pool

Deletes a load balancer pool.

Error response codes:204,400,401,413,503,500,

Request

Name In Type Description
pool_id (Optional) path string The UUID for the pool.
GET
/v2.0/lb/vips

List VIPs

Lists VIPs.

The list might be empty.

Normal response codes: 200 Error response codes:500,401,503,

Request

Response Parameters

Name In Type Description
status body string The network status.
status_description body string Human-readable description of the status.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
description body string The human-readable description for the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
tenant_id body string The ID of the tenant who owns the resource.
connection_limit (Optional) body integer The maximum number of connections permitted for this load balancer. Default is infinite.
pool_id (Optional) path string The UUID for the pool.
session_persistence (Optional) body object The session persistence algorithm. This algorithm is a dictionary with type and cookie_name keys.
address body string The IP address of the member.
vips body array A list of vip objects.
protocol_port body integer The TCP or UDP port on which to listen.
port_id (Optional) path string The UUID of the port.
id body string The UUID of the network.
name body string Human-readable name of the resource.

Response Example

{
    "vips": [
        {
            "status": "ACTIVE",
            "protocol": "HTTP",
            "description": "",
            "address": "10.0.0.4",
            "protocol_port": 80,
            "port_id": "5328aeea-2988-41c0-b5fe-0fd0660979d3",
            "id": "388c739a-6a57-4e74-bc7b-a5cd60248bba",
            "status_description": null,
            "name": "my-Vip",
            "admin_state_up": true,
            "subnet_id": "aa547115-d710-4d6d-bb2c-b038d9c2704b",
            "tenant_id": "eabfefa3fd1740a88a47ad98e132d238",
            "connection_limit": -1,
            "pool_id": "5a9a3e9e-d1aa-448e-af37-a70171f2a332",
            "session_persistence": null
        }
    ]
}
POST
/v2.0/lb/vips

Create a load balancer VIP

Creates a load balancer VIP.

Error response codes:201,400,404,500,401,413,503,409,

Request

Name In Type Description
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
description body string The human-readable description for the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
tenant_id body string The ID of the tenant who owns the resource.
connection_limit (Optional) body integer The maximum number of connections permitted for this load balancer. Default is infinite.
pool_id (Optional) path string The UUID for the pool.
session_persistence (Optional) body object The session persistence algorithm. This algorithm is a dictionary with type and cookie_name keys.
vip body object A vip object.
address body string The IP address of the member.
protocol_port body integer The TCP or UDP port on which to listen.
name body string Human-readable name of the resource.

Request Example

{
    "vip": {
        "protocol": "HTTP",
        "name": "NewVip",
        "admin_state_up": true,
        "subnet_id": "0ba2ef27-0054-4b28-a8fa-f215e8079272",
        "pool_id": "105320c3-8416-4997-9c1c-4098b95fdaca",
        "protocol_port": "80"
    }
}

Response Parameters

Name In Type Description
status body string The network status.
status_description body string Human-readable description of the status.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
description body string The human-readable description for the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
tenant_id body string The ID of the tenant who owns the resource.
connection_limit (Optional) body integer The maximum number of connections permitted for this load balancer. Default is infinite.
pool_id (Optional) path string The UUID for the pool.
session_persistence (Optional) body object The session persistence algorithm. This algorithm is a dictionary with type and cookie_name keys.
vip body object A vip object.
address body string The IP address of the member.
protocol_port body integer The TCP or UDP port on which to listen.
port_id (Optional) path string The UUID of the port.
id body string The UUID of the network.
name body string Human-readable name of the resource.
GET
/v2.0/lb/vips/{vip_id}

Show VIP details

Shows details for a VIP.

Normal response codes: 200 Error response codes:404,403,500,401,413,503,409,

Request

Name In Type Description
vip_id body string The UUID of the virtual IP (VIP) address.

Response Parameters

Name In Type Description
status body string The network status.
status_description body string Human-readable description of the status.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
description body string The human-readable description for the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
tenant_id body string The ID of the tenant who owns the resource.
connection_limit (Optional) body integer The maximum number of connections permitted for this load balancer. Default is infinite.
pool_id (Optional) path string The UUID for the pool.
session_persistence (Optional) body object The session persistence algorithm. This algorithm is a dictionary with type and cookie_name keys.
vip body object A vip object.
address body string The IP address of the member.
protocol_port body integer The TCP or UDP port on which to listen.
port_id (Optional) path string The UUID of the port.
id body string The UUID of the network.
name body string Human-readable name of the resource.

Response Example

{
    "vip": {
        "status": "ACTIVE",
        "protocol": "HTTP",
        "description": "",
        "address": "10.0.0.4",
        "protocol_port": 80,
        "port_id": "5328aeea-2988-41c0-b5fe-0fd0660979d3",
        "id": "388c739a-6a57-4e74-bc7b-a5cd60248bba",
        "status_description": null,
        "name": "my-Vip",
        "admin_state_up": true,
        "subnet_id": "aa547115-d710-4d6d-bb2c-b038d9c2704b",
        "tenant_id": "eabfefa3fd1740a88a47ad98e132d238",
        "connection_limit": -1,
        "pool_id": "5a9a3e9e-d1aa-448e-af37-a70171f2a332",
        "session_persistence": null
    }
}
PUT
/v2.0/lb/vips/{vip_id}

Update VIP

Updates a load balancer VIP.

Normal response codes: 200 Error response codes:400,401,413,503,500,

Request

Name In Type Description
description body string The human-readable description for the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
connection_limit (Optional) body integer The maximum number of connections permitted for this load balancer. Default is infinite.
pool_id (Optional) path string The UUID for the pool.
session_persistence (Optional) body object The session persistence algorithm. This algorithm is a dictionary with type and cookie_name keys.
vip body object A vip object.
name body string Human-readable name of the resource.
vip_id body string The UUID of the virtual IP (VIP) address.

Request Example

{
    "vip": {
        "connection_limit": "1000"
    }
}

Response Parameters

Name In Type Description
status body string The network status.
status_description body string Human-readable description of the status.
protocol (Optional) body string The IP protocol. Valid value is icmp, tcp, udp, or null. No default.
description body string The human-readable description for the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
subnet_id (Optional) body string If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.
tenant_id body string The ID of the tenant who owns the resource.
connection_limit (Optional) body integer The maximum number of connections permitted for this load balancer. Default is infinite.
pool_id (Optional) path string The UUID for the pool.
session_persistence (Optional) body object The session persistence algorithm. This algorithm is a dictionary with type and cookie_name keys.
vip body object A vip object.
address body string The IP address of the member.
protocol_port body integer The TCP or UDP port on which to listen.
port_id (Optional) path string The UUID of the port.
id body string The UUID of the network.
name body string Human-readable name of the resource.

Response Example

{
    "vip": {
        "status": "PENDING_UPDATE",
        "protocol": "HTTP",
        "description": "",
        "address": "10.0.0.4",
        "protocol_port": 80,
        "port_id": "0ba4cd9c-edb4-4594-bac4-b68b49d5f04c",
        "id": "fa0373e0-9dd4-4ff7-98fc-8cceca9bdb4e",
        "status_description": null,
        "name": "NewVip",
        "admin_state_up": true,
        "subnet_id": "0ba2ef27-0054-4b28-a8fa-f215e8079272",
        "tenant_id": "e68c3e65e1f34ee9b2357d0fe418a78b",
        "connection_limit": 1000,
        "pool_id": "105320c3-8416-4997-9c1c-4098b95fdaca",
        "session_persistence": null
    }
}
DELETE
/v2.0/lb/vips/{vip_id}

Delete VIP

Deletes a load balancer VIP.

Error response codes:204,400,401,413,503,500,

Request

Name In Type Description
vip_id body string The UUID of the virtual IP (VIP) address.
GET
/v2.0/lb/members

List members

Lists members.

Normal response codes: 200 Error response codes:400,401,413,503,500,

Request

Response Parameters

Name In Type Description
status body string The network status.
status_description body string Human-readable description of the status.
weight (Optional) body integer A positive integer value that indicates the relative portion of traffic that this member should receive from the pool. For example, a member with a weight of 10 receives five times as much traffic as a member with a weight of 2.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
pool_id (Optional) path string The UUID for the pool.
members body array The list of members that belong to the pool.
address body string The IP address of the member.
protocol_port body integer The TCP or UDP port on which to listen.
id body string The UUID of the network.

Response Example

{
    "members": [
        {
            "admin_state_up": true,
            "status": "ACTIVE",
            "status_description": null,
            "weight": 1,
            "address": "10.0.1.22",
            "tenant_id": "eabfefa3fd1740a88a47ad98e132d238",
            "protocol_port": 90,
            "id": "cf024846-7516-4e3a-b0fb-6590322c836f",
            "pool_id": "5a9a3e9e-d1aa-448e-af37-a70171f2a332"
        }
    ]
}
POST
/v2.0/lb/members

Create a load balancer member

Creates a load balancer member.

Error response codes:201,400,401,413,503,500,

Request

Name In Type Description
weight (Optional) body integer A positive integer value that indicates the relative portion of traffic that this member should receive from the pool. For example, a member with a weight of 10 receives five times as much traffic as a member with a weight of 2.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
pool_id (Optional) path string The UUID for the pool.
member body object A member object.
address body string The IP address of the member.
protocol_port body integer The TCP or UDP port on which to listen.

Request Example

{
    "member": {
        "address": "10.0.0.22",
        "admin_state_up": true,
        "protocol_port": "90",
        "pool_id": "5a9a3e9e-d1aa-448e-af37-a70171f2a332",
        "weight": "1"
    }
}

Response Parameters

Name In Type Description
status body string The network status.
status_description body string Human-readable description of the status.
weight (Optional) body integer A positive integer value that indicates the relative portion of traffic that this member should receive from the pool. For example, a member with a weight of 10 receives five times as much traffic as a member with a weight of 2.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
pool_id (Optional) path string The UUID for the pool.
member body object A member object.
address body string The IP address of the member.
protocol_port body integer The TCP or UDP port on which to listen.
id body string The UUID of the network.
GET
/v2.0/lb/members/{member_id}

Show member details

Shows details for a member.

Normal response codes: 200 Error response codes:400,401,413,503,500,

Request

Name In Type Description
member_id (Optional) path string The UUID for the member.

Response Parameters

Name In Type Description
status body string The network status.
status_description body string Human-readable description of the status.
weight (Optional) body integer A positive integer value that indicates the relative portion of traffic that this member should receive from the pool. For example, a member with a weight of 10 receives five times as much traffic as a member with a weight of 2.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
pool_id (Optional) path string The UUID for the pool.
member body object A member object.
address body string The IP address of the member.
protocol_port body integer The TCP or UDP port on which to listen.
id body string The UUID of the network.

Response Example

{
    "member": {
        "admin_state_up": true,
        "status": "ACTIVE",
        "status_description": null,
        "weight": 1,
        "address": "10.0.1.22",
        "tenant_id": "eabfefa3fd1740a88a47ad98e132d238",
        "protocol_port": 90,
        "id": "cf024846-7516-4e3a-b0fb-6590322c836f",
        "pool_id": "5a9a3e9e-d1aa-448e-af37-a70171f2a332"
    }
}
PUT
/v2.0/lb/members/{member_id}

Update member

Updates a load balancer member.

Normal response codes: 200 Error response codes:400,401,413,503,500,

Request

Name In Type Description
member body object A member object.
pool_id (Optional) path string The UUID for the pool.
weight (Optional) body integer A positive integer value that indicates the relative portion of traffic that this member should receive from the pool. For example, a member with a weight of 10 receives five times as much traffic as a member with a weight of 2.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
member_id (Optional) path string The UUID for the member.

Request Example

{
    "member": {
        "weight": 5
    }
}

Response Parameters

Name In Type Description
status body string The network status.
status_description body string Human-readable description of the status.
weight (Optional) body integer A positive integer value that indicates the relative portion of traffic that this member should receive from the pool. For example, a member with a weight of 10 receives five times as much traffic as a member with a weight of 2.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
tenant_id body string The ID of the tenant who owns the resource.
pool_id (Optional) path string The UUID for the pool.
member body object A member object.
address body string The IP address of the member.
protocol_port body integer The TCP or UDP port on which to listen.
id body string The UUID of the network.

Response Example

{
    "member": {
        "admin_state_up": true,
        "status": "PENDING_UPDATE",
        "status_description": null,
        "weight": 5,
        "address": "10.0.1.22",
        "tenant_id": "eabfefa3fd1740a88a47ad98e132d238",
        "protocol_port": 90,
        "id": "cf024846-7516-4e3a-b0fb-6590322c836f",
        "pool_id": "5a9a3e9e-d1aa-448e-af37-a70171f2a332"
    }
}
DELETE
/v2.0/lb/members/{member_id}

Delete member

Deletes a load balancer member.

Error response codes:204,400,401,413,503,500,

Request

Name In Type Description
member_id (Optional) path string The UUID for the member.
GET
/v2.0/lb/health_monitors

List health monitors

Lists health monitors.

Normal response codes: 200 Error response codes:400,401,413,503,500,

Request

Response Parameters

Name In Type Description
health_monitors (Optional) body array List of health monitors that are associated with the pool.
tenant_id body string The ID of the tenant who owns the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
delay body integer The time, in seconds, between sending probes to members.
expected_codes (Optional) body string The list of HTTP status codes expected in response from the member to declare it healthy. Specify one of the following values: - A single value, such as 200. - A list, such as 200, 202. - A range, such as 200-204.
max_retries body integer The number of allowed connection failures before changing the status of the member to INACTIVE. A valid value is from 1 to 10.
http_method (Optional) body string The HTTP method that the monitor uses for requests.
timeout body integer The maximum time, in seconds, that a monitor waits to connect before it times out. This value must be less than the delay value.
pools body array List of pools that are associated with the health monitor.
url_path (Optional) body string The HTTP path of the request sent by the monitor to test the health of a member. A valid value is a string that begins with a forward slash (/).
type body string The type of probe sent by the load balancer to verify the member state. A valid value is PING, TCP, HTTP, or HTTPS.
id body string The UUID of the network.

Response Example

{
    "health_monitors": [
        {
            "admin_state_up": true,
            "tenant_id": "eabfefa3fd1740a88a47ad98e132d238",
            "delay": 1,
            "expected_codes": "200,201,202",
            "max_retries": 5,
            "http_method": "GET",
            "timeout": 1,
            "pools": [
                {
                    "status": "ACTIVE",
                    "status_description": null,
                    "pool_id": "5a9a3e9e-d1aa-448e-af37-a70171f2a332"
                }
            ],
            "url_path": "/index.html",
            "type": "HTTP",
            "id": "b7633ade-24dc-4d72-8475-06aa22be5412"
        }
    ]
}
POST
/v2.0/lb/health_monitors

Create a load balancer health monitor

Creates a load balancer health monitor.

Error response codes:201,400,401,413,503,500,

Request

Name In Type Description
health_monitor body object A health_monitor object.
tenant_id body string The ID of the tenant who owns the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
delay body integer The time, in seconds, between sending probes to members.
expected_codes (Optional) body string The list of HTTP status codes expected in response from the member to declare it healthy. Specify one of the following values: - A single value, such as 200. - A list, such as 200, 202. - A range, such as 200-204.
max_retries body integer The number of allowed connection failures before changing the status of the member to INACTIVE. A valid value is from 1 to 10.
http_method (Optional) body string The HTTP method that the monitor uses for requests.
timeout body integer The maximum time, in seconds, that a monitor waits to connect before it times out. This value must be less than the delay value.
url_path (Optional) body string The HTTP path of the request sent by the monitor to test the health of a member. A valid value is a string that begins with a forward slash (/).
type body string The type of probe sent by the load balancer to verify the member state. A valid value is PING, TCP, HTTP, or HTTPS.

Request Example

{
    "health_monitor": {
        "admin_state_up": true,
        "delay": "1",
        "expected_codes": "200,201,202",
        "http_method": "GET",
        "max_retries": 5,
        "timeout": 1,
        "type": "HTTP",
        "url_path": "/index.html"
    }
}

Response Parameters

Name In Type Description
health_monitor body object A health_monitor object.
tenant_id body string The ID of the tenant who owns the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
delay body integer The time, in seconds, between sending probes to members.
expected_codes (Optional) body string The list of HTTP status codes expected in response from the member to declare it healthy. Specify one of the following values: - A single value, such as 200. - A list, such as 200, 202. - A range, such as 200-204.
max_retries body integer The number of allowed connection failures before changing the status of the member to INACTIVE. A valid value is from 1 to 10.
http_method (Optional) body string The HTTP method that the monitor uses for requests.
timeout body integer The maximum time, in seconds, that a monitor waits to connect before it times out. This value must be less than the delay value.
pools body array List of pools that are associated with the health monitor.