Networking API v2.0 extensions (CURRENT)

Extensions

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

GET
/v2.0/extensions
List extensions

Lists available Networking API extensions.

 
Normal response codes
200, 203
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413)
Response parameters
Parameter Style Type Description
next (Optional) plain xsd:anyURI Moves to the next item in the list.
previous (Optional) plain xsd:anyURI Moves to the previous item in the list.
{
    "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"
        }
    ]
}
<?xml version='1.0' encoding='UTF-8'?>
<extensions xmlns="http://openstack.org/quantum/api/v2.0"
    xmlns:quantum="http://openstack.org/quantum/api/v2.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <extension>
        <updated>2013-01-20T00:00:00-00:00</updated>
        <name>Neutron Service Type Management</name>
        <links quantum:type="list"/>
        <alias>service-type</alias>
        <description>API for retrieving service providers for Neutron
            advanced services</description>
    </extension>
    <extension>
        <updated>2012-10-05T10:00:00-00:00</updated>
        <name>security-group</name>
        <links quantum:type="list"/>
        <alias>security-group</alias>
        <description>The security groups extension.</description>
    </extension>
    <extension>
        <updated>2013-02-07T10:00:00-00:00</updated>
        <name>L3 Agent Scheduler</name>
        <links quantum:type="list"/>
        <alias>l3_agent_scheduler</alias>
        <description>Schedule routers among l3 agents</description>
    </extension>
    <extension>
        <updated>2013-02-07T10:00:00-00:00</updated>
        <name>Loadbalancer Agent Scheduler</name>
        <links quantum:type="list"/>
        <alias>lbaas_agent_scheduler</alias>
        <description>Schedule pools among lbaas agents</description>
    </extension>
    <extension>
        <updated>2013-03-28T10:00:00-00:00</updated>
        <name>Neutron L3 Configurable external gateway mode</name>
        <links quantum:type="list"/>
        <alias>ext-gw-mode</alias>
        <description>Extension of the router abstraction for
            specifying whether SNAT should occur on the external
            gateway</description>
    </extension>
    <extension>
        <updated>2014-02-03T10:00:00-00:00</updated>
        <name>Port Binding</name>
        <links quantum:type="list"/>
        <alias>binding</alias>
        <description>Expose port bindings of a virtual port to
            external application</description>
    </extension>
    <extension>
        <updated>2012-09-07T10:00:00-00:00</updated>
        <name>Provider Network</name>
        <links quantum:type="list"/>
        <alias>provider</alias>
        <description>Expose mapping of virtual networks to physical
            networks</description>
    </extension>
    <extension>
        <updated>2013-02-03T10:00:00-00:00</updated>
        <name>agent</name>
        <links quantum:type="list"/>
        <alias>agent</alias>
        <description>The agent management extension.</description>
    </extension>
    <extension>
        <updated>2012-07-29T10:00:00-00:00</updated>
        <name>Quota management support</name>
        <links quantum:type="list"/>
        <alias>quotas</alias>
        <description>Expose functions for quotas management per
            tenant</description>
    </extension>
    <extension>
        <updated>2013-02-07T10:00:00-00:00</updated>
        <name>DHCP Agent Scheduler</name>
        <links quantum:type="list"/>
        <alias>dhcp_agent_scheduler</alias>
        <description>Schedule networks among dhcp agents</description>
    </extension>
    <extension>
        <updated>2013-06-27T10:00:00-00:00</updated>
        <name>Multi Provider Network</name>
        <links quantum:type="list"/>
        <alias>multi-provider</alias>
        <description>Expose mapping of virtual networks to multiple
            physical networks</description>
    </extension>
    <extension>
        <updated>2013-01-14T10:00:00-00:00</updated>
        <name>Neutron external network</name>
        <links quantum:type="list"/>
        <alias>external-net</alias>
        <description>Adds external network attribute to network
            resource.</description>
    </extension>
    <extension>
        <updated>2012-07-20T10:00:00-00:00</updated>
        <name>Neutron L3 Router</name>
        <links quantum:type="list"/>
        <alias>router</alias>
        <description>Router abstraction for basic L3 forwarding
            between L2 Neutron networks and access to external
            networks via a NAT gateway.</description>
    </extension>
    <extension>
        <updated>2013-07-23T10:00:00-00:00</updated>
        <name>Allowed Address Pairs</name>
        <links quantum:type="list"/>
        <alias>allowed-address-pairs</alias>
        <description>Provides allowed address pairs</description>
    </extension>
    <extension>
        <updated>2013-03-17T12:00:00-00:00</updated>
        <name>Neutron Extra DHCP opts</name>
        <links quantum:type="list"/>
        <alias>extra_dhcp_opt</alias>
        <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)</description>
    </extension>
    <extension>
        <updated>2012-10-07T10:00:00-00:00</updated>
        <name>LoadBalancing service</name>
        <links quantum:type="list"/>
        <alias>lbaas</alias>
        <description>Extension for LoadBalancing service</description>
    </extension>
    <extension>
        <updated>2013-02-01T10:00:00-00:00</updated>
        <name>Neutron Extra Route</name>
        <links quantum:type="list"/>
        <alias>extraroute</alias>
        <description>Extra routes configuration for L3
            router</description>
    </extension>
</extensions>

This operation does not accept a request body.

GET
/v2.0/extensions/​{alias}​
Get extension details

Gets detailed information for a specified extension.

 
Normal response codes
200, 203
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413)
Request parameters
Parameter Style Type Description
alias URI xsd:string

The alias of an extension.

{
    "extension": {
        "updated": "2013-02-03T10:00:00-00:00",
        "name": "agent",
        "links": [],
        "alias": "agent",
        "description": "The agent management extension."
    }
}
<?xml version='1.0' encoding='UTF-8'?>
<extension xmlns="http://openstack.org/quantum/api/v2.0"
    xmlns:quantum="http://openstack.org/quantum/api/v2.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <updated>2013-02-03T10:00:00-00:00</updated>
    <name>agent</name>
    <links quantum:type="list"/>
    <alias>agent</alias>
    <description>The agent management extension.</description>
</extension>

This operation does not accept a request body.

Quotas extension (quotas)

Lists, shows information for, updates, and resets quotas.

GET
/v2.0/quotas
List quotas

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

 
Normal response codes
200
Error response codes
unauthorized (401), forbidden (403)
{
    "quotas": [
        {
            "subnet": 10,
            "ikepolicy": -1,
            "subnetpool": -1,
            "network": 15,
            "ipsec_site_connection": -1,
            "floatingip": 50,
            "tenant_id": "b7445f221cda4f4a8ac7db6b218b1339",
            "ipsecpolicy": -1,
            "security_group_rule": 100,
            "vpnservice": -1,
            "security_group": 10,
            "router": 10,
            "port": 30
        },
        {
            "subnet": 10,
            "ikepolicy": -1,
            "subnetpool": -1,
            "network": 5,
            "ipsec_site_connection": -1,
            "floatingip": 50,
            "tenant_id": "666a45fe39fe4e67bd3e542e8fd5087d",
            "ipsecpolicy": -1,
            "security_group_rule": 100,
            "vpnservice": -1,
            "security_group": 10,
            "router": 10,
            "port": 30
        }
    ]
}

This operation does not accept a request body.

GET
/v2.0/quotas/​{tenant_id}​
Show quota

Shows quotas for a specified tenant.

 
Normal response codes
200
Error response codes
unauthorized (401), forbidden (403), itemNotFound (404)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:uuid

The tenant ID.

Response parameters
Parameter Style Type Description
subnet plain xsd:int

The number of subnets allowed for each tenant.

router plain xsd:int

The number of routers allowed for each tenant.

port plain xsd:int

The number of ports allowed for each tenant.

network plain xsd:int

The number of networks allowed for each tenant.

floatingip plain xsd:int

The number of floating IP addresses allowed for each tenant.

subnetpool plain xsd:int

The number of subnet pools allowed for each tenant.

security_group_rule plain xsd:int

The number of security group rules allowed for each tenant.

security_group plain xsd:int

The number of security groups allowed for each tenant.

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

This operation does not accept a request body.

PUT
/v2.0/quotas/​{tenant_id}​
Update quota

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

 
Normal response codes
200
Error response codes
unauthorized (401), forbidden (403), itemNotFound (404)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:uuid

The tenant ID.

Response parameters
Parameter Style Type Description
subnet plain xsd:int

The number of subnets allowed for each tenant.

router plain xsd:int

The number of routers allowed for each tenant.

port plain xsd:int

The number of ports allowed for each tenant.

network plain xsd:int

The number of networks allowed for each tenant.

floatingip plain xsd:int

The number of floating IP addresses allowed for each tenant.

subnetpool plain xsd:int

The number of subnet pools allowed for each tenant.

security_group_rule plain xsd:int

The number of security group rules allowed for each tenant.

security_group plain xsd:int

The number of security groups allowed for each tenant.

{
    "quota": {
        "subnet": 40,
        "router": 50,
        "network": 10,
        "floatingip": 30,
        "port": 30
    }
}
{
    "quota": {
        "subnet": 40,
        "router": 50,
        "port": 30,
        "network": 10,
        "floatingip": 30
    }
}
DELETE
/v2.0/quotas/​{tenant_id}​
Reset quota

Resets quotas to default values for a specified tenant.

 
Normal response codes
204
Error response codes
unauthorized (401), forbidden (403), itemNotFound (404)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:uuid

The tenant ID.

This operation does not accept a request body and does not return a response body.

Networks provider extended attributes (networks)

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

GET
/v2.0/networks
List networks

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

 
Normal response codes
200
Error response codes
unauthorized (401)
Response parameters
Parameter Style Type Description
network plain xsd:dict

A network object.

admin_state_up plain xsd:bool

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

id plain csapi:uuid

The network ID.

name plain xsd:string

The network name.

shared plain xsd:bool

Indicates whether this network is shared across all tenants.

status plain xsd:string

The network status.

subnets plain xsd:dict

The associated subnets.

tenant_id plain csapi:uuid

The tenant ID.

router:external plain xsd:bool

Indicates whether this network is externally accessible.

mtu plain xsd:integer

MTU of a network resource.

port_security_enabled plain xsd:bool

The port security status. A valid value is enabled (true) or disabled (false).

provider:physical_network (Optional) plain xsd: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.

provider:network_type (Optional) plain xsd:string

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

provider:segmentation_id (Optional) plain xsd: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.

{
    "network": {
        "status": "ACTIVE",
        "subnets": [
            "54d6f61d-db07-451c-9ab3-b9609b6b6f0b"
        ],
        "name": "private-network",
        "router:external": false,
        "admin_state_up": true,
        "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
        "mtu": 0,
        "shared": true,
        "port_security_enabled": true,
        "id": "d32019d3-bc6e-4319-9c1d-6722fc136a22"
    }
}
<?xml version='1.0' encoding='UTF-8'?>
<network xmlns="http://openstack.org/quantum/api/v2.0"
    xmlns:provider="http://docs.openstack.org/ext/provider/api/v1.0"
    xmlns:quantum="http://openstack.org/quantum/api/v2.0"
    xmlns:router="http://docs.openstack.org/ext/neutron/router/api/v1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <status>ACTIVE</status>
    <subnets>
        <subnet>54d6f61d-db07-451c-9ab3-b9609b6b6f0b</subnet>
    </subnets>
    <name>private-network</name>
    <admin_state_up quantum:type="bool">True</admin_state_up>
    <tenant_id>4fd44f30292945e481c7b8a0c8908869</tenant_id>
    <shared quantum:type="bool">True</shared>
    <id>d32019d3-bc6e-4319-9c1d-6722fc136a22</id>
</network>

This operation does not accept a request body.

POST
/v2.0/networks
Create network

Creates a network.

 
Normal response codes
201
Error response codes
badRequest (400), unauthorized (401)
Request parameters
Parameter Style Type Description
network plain xsd:dict

A network object.

admin_state_up (Optional) plain xsd:bool

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

name (Optional) plain xsd:string The network name.
shared (Optional) plain xsd:bool

Admin-only. Indicates whether this network is shared across all tenants.

tenant_id (Optional) plain csapi:uuid

The ID of the tenant who owns the network. Only administrative users can specify a tenant ID other than their own. You cannot change this value through authorization policies.

router:external (Optional) plain xsd:bool

Indicates whether this network is externally accessible.

port_security_enabled (Optional) plain xsd:bool

The port security status. A valid value is enabled (true) or disabled (false).

provider:physical_network (Optional) plain xsd: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.

provider:network_type (Optional) plain xsd:string

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

provider:segmentation_id (Optional) plain xsd: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 parameters
Parameter Style Type Description
network plain xsd:dict

A network object.

admin_state_up plain xsd:bool

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

id plain csapi:uuid

The network ID.

name plain xsd:string

The network name.

shared plain xsd:bool

Indicates whether this network is shared across all tenants.

status plain xsd:string

The network status.

subnets plain xsd:dict

The associated subnets.

tenant_id plain csapi:uuid

The tenant ID.

router:external plain xsd:bool

Indicates whether this network is externally accessible.

mtu plain xsd:integer

MTU of a network resource.

port_security_enabled plain xsd:bool

The port security status. A valid value is enabled (true) or disabled (false).

provider:physical_network (Optional) plain xsd: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.

provider:network_type (Optional) plain xsd:string

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

provider:segmentation_id (Optional) plain xsd: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.

{
    "network": {
        "name": "sample_network",
        "admin_state_up": true
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<network>
    <name>sample_network2</name>
</network>
{
    "network": {
        "status": "ACTIVE",
        "subnets": [],
        "name": "net1",
        "admin_state_up": true,
        "tenant_id": "9bacb3c5d39d41a79512987f338cf177",
        "router:external": false,
        "segments": [
            {
                "provider:segmentation_id": 2,
                "provider:physical_network": "8bab8453-1bc9-45af-8c70-f83aa9b50453",
                "provider:network_type": "vlan"
            },
            {
                "provider:segmentation_id": null,
                "provider:physical_network": "8bab8453-1bc9-45af-8c70-f83aa9b50453",
                "provider:network_type": "stt"
            }
        ],
        "shared": false,
        "id": "4e8e5957-649f-477b-9e5b-f1f75b21c03c"
    }
}
<?xml version='1.0' encoding='UTF-8'?>
<network xmlns="http://openstack.org/quantum/api/v2.0"
    xmlns:provider="http://docs.openstack.org/ext/provider/api/v1.0"
    xmlns:quantum="http://openstack.org/quantum/api/v2.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <status>ACTIVE</status>
    <subnets quantum:type="list"/>
    <name>sample_network2</name>
    <provider:physical_network xsi:nil="true"/>
    <admin_state_up quantum:type="bool">True</admin_state_up>
    <tenant_id>4fd44f30292945e481c7b8a0c8908869</tenant_id>
    <provider:network_type>local</provider:network_type>
    <shared quantum:type="bool">False</shared>
    <id>c220b026-ece1-4ead-873f-83537f4c9f92</id>
    <provider:segmentation_id xsi:nil="true"/>
</network>
GET
/v2.0/networks/​{network_id}​
Show network details

Shows details for a specified network.

 
Normal response codes
200
Error response codes
unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
network_id URI csapi:UUID

The UUID for the network of interest to you.

Response parameters
Parameter Style Type Description
network plain xsd:dict

A network object.

admin_state_up plain xsd:bool

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

id plain csapi:uuid

The network ID.

name plain xsd:string

The network name.

shared plain xsd:bool

Indicates whether this network is shared across all tenants.

status plain xsd:string

The network status.

subnets plain xsd:dict

The associated subnets.

tenant_id plain csapi:uuid

The tenant ID.

router:external plain xsd:bool

Indicates whether this network is externally accessible.

mtu plain xsd:integer

MTU of a network resource.

port_security_enabled plain xsd:bool

The port security status. A valid value is enabled (true) or disabled (false).

provider:physical_network (Optional) plain xsd: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.

provider:network_type (Optional) plain xsd:string

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

provider:segmentation_id (Optional) plain xsd: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.

{
    "network": {
        "status": "ACTIVE",
        "subnets": [
            "54d6f61d-db07-451c-9ab3-b9609b6b6f0b"
        ],
        "name": "private-network",
        "router:external": false,
        "admin_state_up": true,
        "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
        "mtu": 0,
        "shared": true,
        "port_security_enabled": true,
        "id": "d32019d3-bc6e-4319-9c1d-6722fc136a22"
    }
}
<?xml version='1.0' encoding='UTF-8'?>
<network xmlns="http://openstack.org/quantum/api/v2.0"
    xmlns:provider="http://docs.openstack.org/ext/provider/api/v1.0"
    xmlns:quantum="http://openstack.org/quantum/api/v2.0"
    xmlns:router="http://docs.openstack.org/ext/neutron/router/api/v1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <status>ACTIVE</status>
    <subnets>
        <subnet>54d6f61d-db07-451c-9ab3-b9609b6b6f0b</subnet>
    </subnets>
    <name>private-network</name>
    <admin_state_up quantum:type="bool">True</admin_state_up>
    <tenant_id>4fd44f30292945e481c7b8a0c8908869</tenant_id>
    <shared quantum:type="bool">True</shared>
    <id>d32019d3-bc6e-4319-9c1d-6722fc136a22</id>
</network>

This operation does not accept a request body.

PUT
/v2.0/networks/​{network_id}​
Update network

Updates a specified network.

 
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
network_id URI csapi:UUID

The UUID for the network of interest to you.

network plain xsd:dict

A network object.

admin_state_up (Optional) plain xsd:bool

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

name (Optional) plain xsd:string The network name.
shared (Optional) plain xsd:bool

Admin-only. Indicates whether this network is shared across all tenants.

tenant_id (Optional) plain csapi:uuid

The ID of the tenant who owns the network. Only administrative users can specify a tenant ID other than their own. You cannot change this value through authorization policies.

router:external (Optional) plain xsd:bool

Indicates whether this network is externally accessible.

port_security_enabled (Optional) plain xsd:bool

The port security status. A valid value is enabled (true) or disabled (false).

provider:physical_network (Optional) plain xsd: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.

provider:network_type (Optional) plain xsd:string

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

provider:segmentation_id (Optional) plain xsd: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 parameters
Parameter Style Type Description
network plain xsd:dict

A network object.

admin_state_up plain xsd:bool

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

id plain csapi:uuid

The network ID.

name plain xsd:string

The network name.

shared plain xsd:bool

Indicates whether this network is shared across all tenants.

status plain xsd:string

The network status.

subnets plain xsd:dict

The associated subnets.

tenant_id plain csapi:uuid

The tenant ID.

router:external plain xsd:bool

Indicates whether this network is externally accessible.

mtu plain xsd:integer

MTU of a network resource.

port_security_enabled plain xsd:bool

The port security status. A valid value is enabled (true) or disabled (false).

provider:physical_network (Optional) plain xsd: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.

provider:network_type (Optional) plain xsd:string

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

provider:segmentation_id (Optional) plain xsd: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.

{
    "network": {
        "name": "sample_network_5_updated"
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<network xmlns="http://openstack.org/quantum/api/v2.0"
    xmlns:provider="http://docs.openstack.org/ext/provider/api/v1.0"
    xmlns:quantum="http://openstack.org/quantum/api/v2.0"
    xmlns:router="http://docs.openstack.org/ext/quantum/router/api/v1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <name>sample-network-4-updated</name>
</network>
{
    "network": {
        "status": "ACTIVE",
        "subnets": [],
        "name": "sample_network_5_updated",
        "provider:physical_network": null,
        "admin_state_up": true,
        "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
        "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
    }
}
<?xml version='1.0' encoding='UTF-8'?>
<network xmlns="http://openstack.org/quantum/api/v2.0"
    xmlns:provider="http://docs.openstack.org/ext/provider/api/v1.0"
    xmlns:quantum="http://openstack.org/quantum/api/v2.0"
    xmlns:router="http://docs.openstack.org/ext/neutron/router/api/v1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <status>ACTIVE</status>
    <subnets quantum:type="list"/>
    <name>sample-network-4-updated</name>
    <provider:physical_network xsi:nil="true"/>
    <admin_state_up quantum:type="bool">True</admin_state_up>
    <tenant_id>4fd44f30292945e481c7b8a0c8908869</tenant_id>
    <provider:network_type>local</provider:network_type>
    <router:external quantum:type="bool">False</router:external>
    <shared quantum:type="bool">False</shared>
    <id>af374017-c9ae-4a1d-b799-ab73111476e2</id>
    <provider:segmentation_id xsi:nil="true"/>
</network>
DELETE
/v2.0/networks/​{network_id}​
Delete network

Deletes a specified network.

 
Normal response codes
204
Error response codes
unauthorized (401), itemNotFound (404), conflict (409)
Request parameters
Parameter Style Type Description
network_id URI csapi:UUID

The UUID for the network of interest to you.

This operation does not accept a request body and does not return a response body.

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 specified network, a VXLAN tunnel ID, and a VLAN.

GET
/v2.0/networks
List networks

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
unauthorized (401)
Response parameters
Parameter Style Type Description
networks plain xsd:dict

A networks object.

admin_state_up plain xsd:bool

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

id plain csapi:uuid

The network ID.

name plain xsd:string

The network name.

shared plain xsd:bool

Indicates whether this network is shared across all tenants.

status plain xsd:string

The network status.

subnets plain xsd:dict

The associated subnets.

tenant_id plain csapi:uuid

The tenant ID.

router:external plain xsd:bool

Indicates whether this network is externally accessible.

mtu plain xsd:integer

MTU of a network resource.

port_security_enabled plain xsd:bool

The port security status. A valid value is enabled (true) or disabled (false).

segments plain xsd:string

A segments object that defines one or more provider segments.

provider:physical_network (Optional) plain xsd: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.

provider:network_type (Optional) plain xsd:string

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

provider:segmentation_id (Optional) plain xsd: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.

{
    "networks": [
        {
            "status": "ACTIVE",
            "subnets": [],
            "name": "net1",
            "admin_state_up": true,
            "tenant_id": "9bacb3c5d39d41a79512987f338cf177",
            "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",
            "provider:network_type": "local",
            "shared": true,
            "id": "db193ab3-96e3-4cb3-8fc5-05f4296d0324",
            "provider:segmentation_id": null
        }
    ]
}

This operation does not accept a request body.

POST
/v2.0/networks
Create network with multiple segment mappings

Creates a network with multiple segment mappings.

 
Normal response codes
201
Error response codes
badRequest (400), unauthorized (401)
Request parameters
Parameter Style Type Description
network plain xsd:dict

A network object.

admin_state_up (Optional) plain xsd:bool

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

name (Optional) plain xsd:string The network name.
shared (Optional) plain xsd:bool

Admin-only. Indicates whether this network is shared across all tenants.

tenant_id (Optional) plain csapi:uuid

The ID of the tenant who owns the network. Only administrative users can specify a tenant ID other than their own. You cannot change this value through authorization policies.

router:external (Optional) plain xsd:bool

Indicates whether this network is externally accessible.

port_security_enabled (Optional) plain xsd:bool

The port security status. A valid value is enabled (true) or disabled (false).

segments plain xsd:string

A segments object that defines one or more provider segments.

provider:physical_network (Optional) plain xsd: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.

provider:network_type (Optional) plain xsd:string

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

provider:segmentation_id (Optional) plain xsd: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 parameters
Parameter Style Type Description
network plain xsd:dict

A network object.

admin_state_up plain xsd:bool

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

id plain csapi:uuid

The network ID.

name plain xsd:string

The network name.

shared plain xsd:bool

Indicates whether this network is shared across all tenants.

status plain xsd:string

The network status.

subnets plain xsd:dict

The associated subnets.

tenant_id plain csapi:uuid

The tenant ID.

router:external plain xsd:bool

Indicates whether this network is externally accessible.

mtu plain xsd:integer

MTU of a network resource.

port_security_enabled plain xsd:bool

The port security status. A valid value is enabled (true) or disabled (false).

provider:physical_network (Optional) plain xsd: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.

provider:network_type (Optional) plain xsd:string

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

provider:segmentation_id (Optional) plain xsd: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.

{
    "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
    }
}
{
    "network": {
        "status": "ACTIVE",
        "subnets": [],
        "name": "net1",
        "admin_state_up": true,
        "tenant_id": "9bacb3c5d39d41a79512987f338cf177",
        "segments": [
            {
                "provider:segmentation_id": 2,
                "provider:physical_network": "8bab8453-1bc9-45af-8c70-f83aa9b50453",
                "provider:network_type": "vlan"
            },
            {
                "provider:segmentation_id": null,
                "provider:physical_network": "8bab8453-1bc9-45af-8c70-f83aa9b50453",
                "provider:network_type": "stt"
            }
        ],
        "shared": false,
        "id": "4e8e5957-649f-477b-9e5b-f1f75b21c03c"
    }
}
GET
/v2.0/networks/​{network_id}​
Show details for a network with multiple segments

Shows details for a specified network with multiple segments.

 
Normal response codes
200
Error response codes
unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
network_id URI csapi:UUID

The UUID for the network of interest to you.

Response parameters
Parameter Style Type Description
network plain xsd:dict

A network object.

admin_state_up plain xsd:bool

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

id plain csapi:uuid

The network ID.

name plain xsd:string

The network name.

shared plain xsd:bool

Indicates whether this network is shared across all tenants.

status plain xsd:string

The network status.

subnets plain xsd:dict

The associated subnets.

tenant_id plain csapi:uuid

The tenant ID.

router:external plain xsd:bool

Indicates whether this network is externally accessible.

mtu plain xsd:integer

MTU of a network resource.

port_security_enabled plain xsd:bool

The port security status. A valid value is enabled (true) or disabled (false).

segments plain xsd:string

A segments object that defines one or more provider segments.

provider:physical_network (Optional) plain xsd: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.

provider:network_type (Optional) plain xsd:string

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

provider:segmentation_id (Optional) plain xsd: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.

{
    "network": {
        "status": "ACTIVE",
        "subnets": [],
        "name": "net1",
        "admin_state_up": true,
        "tenant_id": "9bacb3c5d39d41a79512987f338cf177",
        "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"
    }
}

This operation does not accept a request body.

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
List networks with VLAN transparency attribute

Lists networks. The response shows the VLAN transparency attribute.

 
Normal response codes
200
Error response codes
unauthorized (401)
Response parameters
Parameter Style Type Description
networks plain xsd:dict

A networks object.

admin_state_up plain xsd:bool

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

id plain csapi:uuid

The network ID.

name plain xsd:string

The network name.

shared plain xsd:bool

Indicates whether this network is shared across all tenants.

status plain xsd:string

The network status.

subnets plain xsd:dict

The associated subnets.

tenant_id plain csapi:uuid

The tenant ID.

router:external plain xsd:bool

Indicates whether this network is externally accessible.

mtu plain xsd:integer

MTU of a network resource.

port_security_enabled plain xsd:bool

The port security status. A valid value is enabled (true) or disabled (false).

vlan_transparent plain xsd:bool

The state of the network, which is VLAN transparent (true) or not VLAN transparent (false).

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

This operation does not accept a request body.

POST
/v2.0/networks
Create VLAN-transparent network

Creates a VLAN-transparent network.

 
Normal response codes
201
Error response codes
badRequest (400), unauthorized (401)
Request parameters
Parameter Style Type Description
network plain xsd:dict

A network object.

admin_state_up (Optional) plain xsd:bool

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

name (Optional) plain xsd:string The network name.
shared (Optional) plain xsd:bool

Admin-only. Indicates whether this network is shared across all tenants.

tenant_id (Optional) plain csapi:uuid

The ID of the tenant who owns the network. Only administrative users can specify a tenant ID other than their own. You cannot change this value through authorization policies.

router:external (Optional) plain xsd:bool

Indicates whether this network is externally accessible.

port_security_enabled (Optional) plain xsd:bool

The port security status. A valid value is enabled (true) or disabled (false).

vlan_transparent plain xsd:bool

The state of the network, which is VLAN transparent (true) or not VLAN transparent (false).

Response parameters
Parameter Style Type Description
network plain xsd:dict

A network object.

admin_state_up plain xsd:bool

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

id plain csapi:uuid

The network ID.

name plain xsd:string

The network name.

shared plain xsd:bool

Indicates whether this network is shared across all tenants.

status plain xsd:string

The network status.

subnets plain xsd:dict

The associated subnets.

tenant_id plain csapi:uuid

The tenant ID.

router:external plain xsd:bool

Indicates whether this network is externally accessible.

mtu plain xsd:integer

MTU of a network resource.

port_security_enabled plain xsd:bool

The port security status. A valid value is enabled (true) or disabled (false).

vlan_transparent plain xsd:bool

The state of the network, which is VLAN transparent (true) or not VLAN transparent (false).

{
    "network": {
        "name": "net1",
        "admin_state_up": true,
        "vlan_transparent": true
    }
}
{
    "network": {
        "status": "ACTIVE",
        "subnets": [],
        "name": "net1",
        "admin_state_up": true,
        "vlan_transparent": true,
        "tenant_id": "5831268f-1f52-49a7-88d5-bc0d7a74d523",
        "router:external": false,
        "shared": false,
        "id": "3114f6e9-f9bc-4570-a941-7329b3b9759f"
    }
}
GET
/v2.0/networks/​{network_id}​
Show VLAN-transparent network details

Shows details for a specified VLAN-transparent network.

 
Normal response codes
200
Error response codes
unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
network_id URI csapi:UUID

The UUID for the network of interest to you.

Response parameters
Parameter Style Type Description
network plain xsd:dict

A network object.

admin_state_up plain xsd:bool

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

id plain csapi:uuid

The network ID.

name plain xsd:string

The network name.

shared plain xsd:bool

Indicates whether this network is shared across all tenants.

status plain xsd:string

The network status.

subnets plain xsd:dict

The associated subnets.

tenant_id plain csapi:uuid

The tenant ID.

router:external plain xsd:bool

Indicates whether this network is externally accessible.

mtu plain xsd:integer

MTU of a network resource.

port_security_enabled plain xsd:bool

The port security status. A valid value is enabled (true) or disabled (false).

vlan_transparent plain xsd:bool

The state of the network, which is VLAN transparent (true) or not VLAN transparent (false).

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

This operation does not accept a request body.

Ports binding extended attributes (ports)

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

GET
/v2.0/ports
List ports

Lists ports to which the tenant has access.

 
Normal response codes
200
Error response codes
unauthorized (401)
Request parameters
Parameter Style Type Description
status (Optional) query xsd:string

The port status. Value is ACTIVE or DOWN.

display_name (Optional) query xsd:string

The port name.

admin_state (Optional) query xsd:bool

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

network_id (Optional) query csapi:uuid

The ID of the attached network.

tenant_id (Optional) query csapi:uuid

The ID of the tenant who owns the network. Only administrative users can specify a tenant ID other than their own. You cannot change this value through authorization policies.

device_owner (Optional) query xsd:string

The ID of the entity that uses this port. For example, a DHCP agent.

mac_address (Optional) query xsd:string

The MAC address of the port.

port_id (Optional) query csapi:uuid

The ID of the port.

security_groups (Optional) query csapi:uuid

The IDs of any attached security groups.

device_id (Optional) query csapi:uuid

The ID of the device that uses this port. For example, a virtual server.

Response parameters
Parameter Style Type Description
ports plain xsd:dict

A ports object.

status plain xsd:string

The port status. Value is ACTIVE or DOWN.

name plain xsd:string

The port name.

allowed_address_pairs plain xsd:dict

A set of zero or more allowed address pairs. An address pair consists of an IP address and MAC address.

ip_address plain xsd:string

The IP address.

mac_address plain xsd:string

The MAC address.

admin_state_up plain xsd:bool

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

network_id plain csapi:uuid

The ID of the attached network.

tenant_id plain csapi:uuid

The ID of the tenant who owns the network. Only administrative users can specify a tenant ID other than their own.

extra_dhcp_opts plain xsd:dict

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

opt_value plain xsd:string

The extra DHCP option value.

opt_name plain xsd:string

The extra DHCP option name.

device_owner plain xsd:string

The ID of the entity that uses this port. For example, a DHCP agent.

mac_address plain xsd:string

The MAC address of the port.

fixed_ips plain xsd:dict

IP addresses for the port. Includes the IP address and subnet ID.

subnet_id plain csapi:uuid

Subnet ID of the subnet to which the port is attached.

ip_address plain xsd:string

IP address.

id plain csapi:uuid

The ID of the port.

security_groups plain csapi:uuid

The IDs of any attached security groups.

device_id plain csapi:uuid

The ID of the device that uses this port. For example, a virtual server.

port_security_enabled plain xsd:bool

The port security status. The status is enabled (true) or disabled (false).

binding:host_id (Optional) plain csapi:uuid

The ID of the host where the port is allocated. In some cases, different implementations can run on different hosts.

binding:vif_details (Optional) plain xsd:dict

Read-only. A dictionary that enables the application to pass information about functions that the Networking API provides. To enable or disable port filtering features such as security group and anti-MAC/IP spoofing, specify port_filter: True or port_filter: False.

port_filter (Optional) plain xsd:bool

Read-only. A dictionary that enables the application to pass information about functions that the Networking API provides. To enable or disable port filtering features such as security group and anti-MAC/IP spoofing, specify port_filter: True or port_filter: False.

ovs_hybrid_plug (Optional) plain xsd:bool

Read-only. A dictionary that enables the application to pass information about functions that the Networking API provides. To enable or disable port filtering features such as security group and anti-MAC/IP spoofing, specify port_filter: True or port_filter: False.

binding:vif_type (Optional) plain xsd:string

Read-only. The VIF type for the specified port.

binding:profile (Optional) plain xsd:dict

A dictionary the enables the application running on the specified host to pass and receive VIF port-specific information to the plug-in.

binding:vnic_type (Optional) plain xsd:string

The virtual network interface card (vNIC) type that is bound to the neutron port.

In POST and PUT operations, specify a value of normal (virtual NIC), direct (PCI pass-through), or macvtap (virtual interface with a tap-like software interface). These values support SR-IOV PCI pass-through networking. The ML2 plug-in supports the vnic_type.

In GET operations, the binding:vnic_type extended attribute is visible to only port owners and administrative users.

{
    "ports": [
        {
            "status": "ACTIVE",
            "binding:host_id": "devstack",
            "name": "",
            "allowed_address_pairs": [],
            "admin_state_up": true,
            "network_id": "70c1db1f-b701-45bd-96e0-a313ee3430b3",
            "tenant_id": "",
            "extra_dhcp_opts": [],
            "binding:vif_details": {
                "port_filter": true,
                "ovs_hybrid_plug": true
            },
            "binding:vif_type": "ovs",
            "device_owner": "network:router_gateway",
            "port_security_enabled": true,
            "mac_address": "fa:16:3e:58:42:ed",
            "binding:profile": {},
            "binding:vnic_type": "normal",
            "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",
            "binding:host_id": "devstack",
            "name": "",
            "allowed_address_pairs": [],
            "admin_state_up": true,
            "network_id": "f27aa545-cbdd-4907-b0c6-c9e8b039dcc2",
            "tenant_id": "d397de8a63f341818f198abb0966f6f3",
            "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": true,
            "mac_address": "fa:16:3e:bb:3c:e4",
            "binding:profile": {},
            "binding:vnic_type": "normal",
            "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"
        }
    ]
}
<?xml version='1.0' encoding='UTF-8'?>
<ports xmlns="http://openstack.org/quantum/api/v2.0"
    xmlns:binding="http://docs.openstack.org/ext/binding/api/v1.0"
    xmlns:quantum="http://openstack.org/quantum/api/v2.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <port>
        <status>ACTIVE</status>
        <binding:host_id>devstack</binding:host_id>
        <name/>
        <allowed_address_pairs quantum:type="list"/>
        <admin_state_up quantum:type="bool">True</admin_state_up>
        <network_id>70c1db1f-b701-45bd-96e0-a313ee3430b3</network_id>
        <tenant_id/>
        <extra_dhcp_opts quantum:type="list"/>
        <binding:vif_details>
            <port_filter quantum:type="bool">True</port_filter>
            <ovs_hybrid_plug quantum:type="bool"
                >True</ovs_hybrid_plug>
        </binding:vif_details>
        <binding:vif_type>ovs</binding:vif_type>
        <device_owner>network:router_gateway</device_owner>
        <mac_address>fa:16:3e:58:42:ed</mac_address>
        <binding:profile quantum:type="dict"/>
        <binding:vnic_type>normal</binding:vnic_type>
        <fixed_ips>
            <fixed_ip>
                <subnet_id>008ba151-0b8c-4a67-98b5-0d2b87666062</subnet_id>
                <ip_address>172.24.4.2</ip_address>
            </fixed_ip>
        </fixed_ips>
        <id>d80b1a3b-4fc1-49f3-952e-1e2ab7081d8b</id>
        <security_groups quantum:type="list"/>
        <device_id>9ae135f4-b6e0-4dad-9e91-3c223e385824</device_id>
    </port>
    <port>
        <status>ACTIVE</status>
        <binding:host_id>devstack</binding:host_id>
        <name/>
        <allowed_address_pairs quantum:type="list"/>
        <admin_state_up quantum:type="bool">True</admin_state_up>
        <network_id>f27aa545-cbdd-4907-b0c6-c9e8b039dcc2</network_id>
        <tenant_id>d397de8a63f341818f198abb0966f6f3</tenant_id>
        <extra_dhcp_opts quantum:type="list"/>
        <binding:vif_details>
            <port_filter quantum:type="bool">True</port_filter>
            <ovs_hybrid_plug quantum:type="bool"
                >True</ovs_hybrid_plug>
        </binding:vif_details>
        <binding:vif_type>ovs</binding:vif_type>
        <device_owner>network:router_interface</device_owner>
        <mac_address>fa:16:3e:bb:3c:e4</mac_address>
        <binding:profile quantum:type="dict"/>
        <binding:vnic_type>normal</binding:vnic_type>
        <fixed_ips>
            <fixed_ip>
                <subnet_id>288bf4a1-51ba-43b6-9d0a-520e9005db17</subnet_id>
                <ip_address>10.0.0.1</ip_address>
            </fixed_ip>
        </fixed_ips>
        <id>f71a6703-d6de-4be1-a91a-a570ede1d159</id>
        <security_groups quantum:type="list"/>
        <device_id>9ae135f4-b6e0-4dad-9e91-3c223e385824</device_id>
    </port>
</ports>
POST
/v2.0/ports
Create port

Creates a port on the specified network.

 
Normal response codes
201
Error response codes
badRequest (400), unauthorized (401), forbidden (403)
Request parameters
Parameter Style Type Description
port plain xsd:dict

A port object.

name (Optional) plain xsd:string

A symbolic name for the port.

admin_state_up (Optional) plain xsd:bool

The administrative status of the port, which is up (true) or down (false).

tenant_id (Optional) plain csapi:uuid

The ID of the tenant who owns the network. Only administrative users can specify a tenant ID other than their own. You cannot change this value through authorization policies.

mac_address (Optional) plain xsd:string

The MAC address. If you specify an address that is not valid, a Bad Request (400) status code is returned. If you do not specify a MAC address, OpenStack Networking tries to allocate one. If a failure occurs, a Service Unavailable (503) status code is returned.

fixed_ips (Optional) plain xsd:dict

If you specify only a subnet ID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet ID and an IP address, OpenStack Networking tries to allocate the specified address to the port.

subnet_id (Optional) plain csapi:uuid

If you specify only a subnet ID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet ID and an IP address, OpenStack Networking tries to allocate the specified address to the port.

ip_address (Optional) plain xsd:string

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

security_groups (Optional) plain csapi:uuid

One or more security group IDs.

network_id plain csapi:uuid

The ID of the network.

allowed_address_pairs (Optional) plain xsd:dict

A set of zero or more allowed address pairs. An address pair contains an IP address and MAC address.

ip_address (Optional) plain xsd:string

The IP address of an allowed address pair.

mac_address (Optional) plain xsd:string

The MAC address of an allowed address pair.

opt_value (Optional) plain xsd:string

The extra DHCP option value.

opt_name (Optional) plain xsd:string

The extra DHCP option name.

device_owner (Optional) plain xsd:string

The ID of the entity that uses this port. For example, a DHCP agent.

device_id (Optional) plain csapi:uuid

The ID of the device that uses this port. For example, a virtual server.

binding:host_id (Optional) plain csapi:uuid

The ID of the host where the port is allocated. In some cases, different implementations can run on different hosts.

binding:profile (Optional) plain xsd:dict

A dictionary that enables the application running on the specified host to pass and receive virtual network interface (VIF) port-specific information to the plug-in.

binding:vnic_type (Optional) plain xsd:string

The virtual network interface card (vNIC) type that is bound to the neutron port. A valid value is normal, direct, or macvtap.

Response parameters
Parameter Style Type Description
port plain xsd:dict

A port object.

status plain xsd:string

The port status. Value is ACTIVE or DOWN.

name plain xsd:string

The port name.

allowed_address_pairs plain xsd:dict

A set of zero or more allowed address pairs. An address pair consists of an IP address and MAC address.

ip_address plain xsd:string

The IP address.

mac_address plain xsd:string

The MAC address.

admin_state_up plain xsd:bool

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

network_id plain csapi:uuid

The ID of the attached network.

tenant_id plain csapi:uuid

The ID of the tenant who owns the network. Only administrative users can specify a tenant ID other than their own.

extra_dhcp_opts plain xsd:dict

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

opt_value plain xsd:string

The extra DHCP option value.

opt_name plain xsd:string

The extra DHCP option name.

device_owner plain xsd:string

The ID of the entity that uses this port. For example, a DHCP agent.

mac_address plain xsd:string

The MAC address of the port.

fixed_ips plain xsd:dict

IP addresses for the port. Includes the IP address and subnet ID.

subnet_id plain csapi:uuid

Subnet ID of the subnet to which the port is attached.

ip_address plain xsd:string

IP address.

id plain csapi:uuid

The ID of the port.

security_groups plain csapi:uuid

The IDs of any attached security groups.

device_id plain csapi:uuid

The ID of the device that uses this port. For example, a virtual server.

port_security_enabled plain xsd:bool

The port security status. The status is enabled (true) or disabled (false).

binding:host_id (Optional) plain csapi:uuid

The ID of the host where the port is allocated. In some cases, different implementations can run on different hosts.

binding:vif_details (Optional) plain xsd:dict

Read-only. A dictionary that enables the application to pass information about functions that the Networking API provides. To enable or disable port filtering features such as security group and anti-MAC/IP spoofing, specify port_filter: True or port_filter: False.

port_filter (Optional) plain xsd:bool

Read-only. A dictionary that enables the application to pass information about functions that the Networking API provides. To enable or disable port filtering features such as security group and anti-MAC/IP spoofing, specify port_filter: True or port_filter: False.

ovs_hybrid_plug (Optional) plain xsd:bool

Read-only. A dictionary that enables the application to pass information about functions that the Networking API provides. To enable or disable port filtering features such as security group and anti-MAC/IP spoofing, specify port_filter: True or port_filter: False.

binding:vif_type (Optional) plain xsd:string

Read-only. The VIF type for the specified port.

binding:profile (Optional) plain xsd:dict

A dictionary the enables the application running on the specified host to pass and receive VIF port-specific information to the plug-in.

binding:vnic_type (Optional) plain xsd:string

The virtual network interface card (vNIC) type that is bound to the neutron port.

In POST and PUT operations, specify a value of normal (virtual NIC), direct (PCI pass-through), or macvtap (virtual interface with a tap-like software interface). These values support SR-IOV PCI pass-through networking. The ML2 plug-in supports the vnic_type.

In GET operations, the binding:vnic_type extended attribute is visible to only port owners and administrative users.

{
    "port": {
        "network_id": "ee2d3158-3e80-4fb3-ba87-c99f515d85e7",
        "admin_state_up": true
    }
}
{
    "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": ""
    }
}
<?xml version='1.0' encoding='UTF-8'?>
<port xmlns="http://openstack.org/quantum/api/v2.0"
    xmlns:binding="http://docs.openstack.org/ext/binding/api/v1.0"
    xmlns:quantum="http://openstack.org/quantum/api/v2.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <status>DOWN</status>
    <binding:host_id/>
    <name>test_port_1</name>
    <allowed_address_pairs quantum:type="list"/>
    <admin_state_up quantum:type="bool">True</admin_state_up>
    <network_id>a87cc70a-3e15-4acf-8205-9b711a3531b7</network_id>
    <tenant_id>d6700c0c9ffa4f1cb322cd4a1f3906fa</tenant_id>
    <binding:vif_details quantum:type="dict"/>
    <binding:vnic_type>normal</binding:vnic_type>
    <binding:vif_type>unbound</binding:vif_type>
    <device_owner/>
    <mac_address>fa:16:3e:09:e3:47</mac_address>
    <binding:profile quantum:type="dict"/>
    <fixed_ips>
        <fixed_ip>
            <subnet_id>a0304c3a-4f08-4c43-88af-d796509c97d2</subnet_id>
            <ip_address>10.0.0.4</ip_address>
        </fixed_ip>
    </fixed_ips>
    <id>8021790b-4bfd-46ab-bcc7-0ef2f73bff43</id>
    <security_groups>
        <security_group>f0ac4394-7e4a-4409-9701-ba8be283dbc3</security_group>
    </security_groups>
    <device_id/>
</port>
GET
/v2.0/ports/​{port_id}​
Show port

Shows information for the specified port.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
port_id URI csapi:UUID

The UUID for the port of interest to you.

Response parameters
Parameter Style Type Description
port plain xsd:dict

A port object.

status plain xsd:string

The port status. Value is ACTIVE or DOWN.

name plain xsd:string

The port name.

allowed_address_pairs plain xsd:dict

A set of zero or more allowed address pairs. An address pair consists of an IP address and MAC address.

ip_address plain xsd:string

The IP address.

mac_address plain xsd:string

The MAC address.

admin_state_up plain xsd:bool

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

network_id plain csapi:uuid

The ID of the attached network.

tenant_id plain csapi:uuid

The ID of the tenant who owns the network. Only administrative users can specify a tenant ID other than their own.

extra_dhcp_opts plain xsd:dict

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

opt_value plain xsd:string

The extra DHCP option value.

opt_name plain xsd:string

The extra DHCP option name.

device_owner plain xsd:string

The ID of the entity that uses this port. For example, a DHCP agent.

mac_address plain xsd:string

The MAC address of the port.

fixed_ips plain xsd:dict

IP addresses for the port. Includes the IP address and subnet ID.

subnet_id plain csapi:uuid

Subnet ID of the subnet to which the port is attached.

ip_address plain xsd:string

IP address.

id plain csapi:uuid

The ID of the port.

security_groups plain csapi:uuid

The IDs of any attached security groups.

device_id plain csapi:uuid

The ID of the device that uses this port. For example, a virtual server.

port_security_enabled plain xsd:bool

The port security status. The status is enabled (true) or disabled (false).

binding:host_id (Optional) plain csapi:uuid

The ID of the host where the port is allocated. In some cases, different implementations can run on different hosts.

binding:vif_details (Optional) plain xsd:dict

Read-only. A dictionary that enables the application to pass information about functions that the Networking API provides. To enable or disable port filtering features such as security group and anti-MAC/IP spoofing, specify port_filter: True or port_filter: False.

port_filter (Optional) plain xsd:bool

Read-only. A dictionary that enables the application to pass information about functions that the Networking API provides. To enable or disable port filtering features such as security group and anti-MAC/IP spoofing, specify port_filter: True or port_filter: False.

ovs_hybrid_plug (Optional) plain xsd:bool

Read-only. A dictionary that enables the application to pass information about functions that the Networking API provides. To enable or disable port filtering features such as security group and anti-MAC/IP spoofing, specify port_filter: True or port_filter: False.

binding:vif_type (Optional) plain xsd:string

Read-only. The VIF type for the specified port.

binding:profile (Optional) plain xsd:dict

A dictionary the enables the application running on the specified host to pass and receive VIF port-specific information to the plug-in.

binding:vnic_type (Optional) plain xsd:string

The virtual network interface card (vNIC) type that is bound to the neutron port.

In POST and PUT operations, specify a value of normal (virtual NIC), direct (PCI pass-through), or macvtap (virtual interface with a tap-like software interface). These values support SR-IOV PCI pass-through networking. The ML2 plug-in supports the vnic_type.

In GET operations, the binding:vnic_type extended attribute is visible to only port owners and administrative users.

{
    "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"
    }
}
<?xml version='1.0' encoding='UTF-8'?>
<port xmlns="http://openstack.org/quantum/api/v2.0"
    xmlns:binding="http://docs.openstack.org/ext/binding/api/v1.0"
    xmlns:quantum="http://openstack.org/quantum/api/v2.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <status>ACTIVE</status>
    <binding:host_id>devstack</binding:host_id>
    <name/>
    <allowed_address_pairs quantum:type="list"/>
    <admin_state_up quantum:type="bool">True</admin_state_up>
    <network_id>a87cc70a-3e15-4acf-8205-9b711a3531b7</network_id>
    <tenant_id>7e02058126cc4950b75f9970368ba177</tenant_id>
    <extra_dhcp_opts quantum:type="list"/>
    <binding:vif_details>
        <port_filter quantum:type="bool">True</port_filter>
        <ovs_hybrid_plug quantum:type="bool">True</ovs_hybrid_plug>
    </binding:vif_details>
    <binding:vif_type>ovs</binding:vif_type>
    <device_owner>network:router_interface</device_owner>
    <mac_address>fa:16:3e:23:fd:d7</mac_address>
    <binding:profile quantum:type="dict"/>
    <binding:vnic_type>normal</binding:vnic_type>
    <fixed_ips>
        <fixed_ip>
            <subnet_id>a0304c3a-4f08-4c43-88af-d796509c97d2</subnet_id>
            <ip_address>10.0.0.1</ip_address>
        </fixed_ip>
    </fixed_ips>
    <id>46d4bfb9-b26e-41f3-bd2e-e6dcc1ccedb2</id>
    <security_groups quantum:type="list"/>
    <device_id>5e3898d7-11be-483e-9732-b2f5eccd2b2e</device_id>
</port>

This operation does not accept a request body.

PUT
/v2.0/ports/​{port_id}​
Update port

Updates the specified port.

 
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
port_id URI csapi:UUID

The UUID for the port of interest to you.

port plain xsd:dict

A port object.

name (Optional) plain xsd:string

A symbolic name for the port.

admin_state_up (Optional) plain xsd:bool

The administrative status of the port, which is up (true) or down (false).

tenant_id (Optional) plain csapi:uuid

The ID of the tenant who owns the network. Only administrative users can specify a tenant ID other than their own. You cannot change this value through authorization policies.

mac_address (Optional) plain xsd:string

The MAC address. If you specify an address that is not valid, a Bad Request (400) status code is returned. If you do not specify a MAC address, OpenStack Networking tries to allocate one. If a failure occurs, a Service Unavailable (503) status code is returned.

fixed_ips (Optional) plain xsd:dict

If you specify only a subnet ID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet ID and an IP address, OpenStack Networking tries to allocate the specified address to the port.

subnet_id (Optional) plain csapi:uuid

If you specify only a subnet ID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet ID and an IP address, OpenStack Networking tries to allocate the specified address to the port.

ip_address (Optional) plain xsd:string

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

security_groups (Optional) plain csapi:uuid

One or more security group IDs.

network_id plain csapi:uuid

The ID of the network.

allowed_address_pairs (Optional) plain xsd:dict

A set of zero or more allowed address pairs. An address pair contains an IP address and MAC address.

ip_address (Optional) plain xsd:string

The IP address of an allowed address pair.

mac_address (Optional) plain xsd:string

The MAC address of an allowed address pair.

opt_value (Optional) plain xsd:string

The extra DHCP option value.

opt_name (Optional) plain xsd:string

The extra DHCP option name.

device_owner (Optional) plain xsd:string

The ID of the entity that uses this port. For example, a DHCP agent.

device_id (Optional) plain csapi:uuid

The ID of the device that uses this port. For example, a virtual server.

binding:host_id (Optional) plain csapi:uuid

The ID of the host where the port is allocated. In some cases, different implementations can run on different hosts.

binding:profile (Optional) plain xsd:dict

A dictionary that enables the application running on the specified host to pass and receive virtual network interface (VIF) port-specific information to the plug-in.

binding:vnic_type (Optional) plain xsd:string

The virtual network interface card (vNIC) type that is bound to the neutron port. A valid value is normal, direct, or macvtap.

Response parameters
Parameter Style Type Description
port plain xsd:dict

A port object.

status plain xsd:string

The port status. Value is ACTIVE or DOWN.

name plain xsd:string

The port name.

allowed_address_pairs plain xsd:dict

A set of zero or more allowed address pairs. An address pair consists of an IP address and MAC address.

ip_address plain xsd:string

The IP address.

mac_address plain xsd:string

The MAC address.

admin_state_up plain xsd:bool

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

network_id plain csapi:uuid

The ID of the attached network.

tenant_id plain csapi:uuid

The ID of the tenant who owns the network. Only administrative users can specify a tenant ID other than their own.

extra_dhcp_opts plain xsd:dict

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

opt_value plain xsd:string

The extra DHCP option value.

opt_name plain xsd:string

The extra DHCP option name.

device_owner plain xsd:string

The ID of the entity that uses this port. For example, a DHCP agent.

mac_address plain xsd:string

The MAC address of the port.

fixed_ips plain xsd:dict

IP addresses for the port. Includes the IP address and subnet ID.

subnet_id plain csapi:uuid

Subnet ID of the subnet to which the port is attached.

ip_address plain xsd:string

IP address.

id plain csapi:uuid

The ID of the port.

security_groups plain csapi:uuid

The IDs of any attached security groups.

device_id plain csapi:uuid

The ID of the device that uses this port. For example, a virtual server.

port_security_enabled plain xsd:bool

The port security status. The status is enabled (true) or disabled (false).

binding:host_id (Optional) plain csapi:uuid

The ID of the host where the port is allocated. In some cases, different implementations can run on different hosts.

binding:vif_details (Optional) plain xsd:dict

Read-only. A dictionary that enables the application to pass information about functions that the Networking API provides. To enable or disable port filtering features such as security group and anti-MAC/IP spoofing, specify port_filter: True or port_filter: False.

port_filter (Optional) plain xsd:bool

Read-only. A dictionary that enables the application to pass information about functions that the Networking API provides. To enable or disable port filtering features such as security group and anti-MAC/IP spoofing, specify port_filter: True or port_filter: False.

ovs_hybrid_plug (Optional) plain xsd:bool

Read-only. A dictionary that enables the application to pass information about functions that the Networking API provides. To enable or disable port filtering features such as security group and anti-MAC/IP spoofing, specify port_filter: True or port_filter: False.

binding:vif_type (Optional) plain xsd:string

Read-only. The VIF type for the specified port.

binding:profile (Optional) plain xsd:dict

A dictionary the enables the application running on the specified host to pass and receive VIF port-specific information to the plug-in.

binding:vnic_type (Optional) plain xsd:string

The virtual network interface card (vNIC) type that is bound to the neutron port.

In POST and PUT operations, specify a value of normal (virtual NIC), direct (PCI pass-through), or macvtap (virtual interface with a tap-like software interface). These values support SR-IOV PCI pass-through networking. The ML2 plug-in supports the vnic_type.

In GET operations, the binding:vnic_type extended attribute is visible to only port owners and administrative users.

{
    "port": {
        "network_id": "ee2d3158-3e80-4fb3-ba87-c99f515d85e7",
        "admin_state_up": true
    }
}
{
    "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": ""
    }
}
<?xml version='1.0' encoding='UTF-8'?>
<port xmlns="http://openstack.org/quantum/api/v2.0"
    xmlns:binding="http://docs.openstack.org/ext/binding/api/v1.0"
    xmlns:quantum="http://openstack.org/quantum/api/v2.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <status>DOWN</status>
    <binding:host_id/>
    <name>test_port_1</name>
    <allowed_address_pairs quantum:type="list"/>
    <admin_state_up quantum:type="bool">True</admin_state_up>
    <network_id>a87cc70a-3e15-4acf-8205-9b711a3531b7</network_id>
    <tenant_id>d6700c0c9ffa4f1cb322cd4a1f3906fa</tenant_id>
    <binding:vif_details quantum:type="dict"/>
    <binding:vnic_type>normal</binding:vnic_type>
    <binding:vif_type>unbound</binding:vif_type>
    <device_owner/>
    <mac_address>fa:16:3e:09:e3:47</mac_address>
    <binding:profile quantum:type="dict"/>
    <fixed_ips>
        <fixed_ip>
            <subnet_id>a0304c3a-4f08-4c43-88af-d796509c97d2</subnet_id>
            <ip_address>10.0.0.4</ip_address>
        </fixed_ip>
    </fixed_ips>
    <id>8021790b-4bfd-46ab-bcc7-0ef2f73bff43</id>
    <security_groups>
        <security_group>f0ac4394-7e4a-4409-9701-ba8be283dbc3</security_group>
    </security_groups>
    <device_id/>
</port>
DELETE
/v2.0/ports/​{port_id}​
Delete port

Deletes the specified port.

 
Normal response codes
204
Error response codes
unauthorized (401), itemNotFound (404), conflict (409)
Request parameters
Parameter Style Type Description
port_id URI csapi:UUID

The UUID for the port of interest to you.

This operation does not accept a request body and does not return a response body.

Security groups (security-groups)

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

GET
/v2.0/security-groups
List security groups

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

 

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

Normal response codes
200
Error response codes
unauthorized (401)
Response parameters
Parameter Style Type Description
security_group plain xsd:dict

A security_group object.

description plain xsd:string

The security group description.

id plain csapi:uuid

The UUID for the security group.

name plain xsd:string

The security group name.

security_group_rules plain xsd:dict

Security group rules.

direction plain xsd:string

Ingress or egress: the direction in which the security group rule is applied. For a compute instance, an ingress security group rule is applied to incoming (ingress) traffic for that instance. An egress rule is applied to traffic leaving the instance.

ethertype plain xsd:string

Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.

id plain csapi:uuid

The UUID of the security group rule.

port_range_max plain xsd:int

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.

port_range_min plain xsd:int

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.

protocol plain xsd:string

The protocol that is matched by the security group rule. Valid values are null, tcp, udp, and icmp.

remote_group_id plain csapi:uuid

The remote group ID to be associated with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body.

remote_ip_prefix plain xsd:string

The remote IP prefix to be associated with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body. This attribute value matches the specified IP prefix as the source IP address of the IP packet.

security_group_id plain csapi:uuid

The ID of the security group.

tenant_id plain csapi:uuid

The ID of the tenant who owns the security group rule. Only administrative users can specify a tenant ID other than their own.

GET /v2.0/security-groups
Accept: application/json
{
    "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.

Normal response codes
201
Error response codes
badRequest (400), unauthorized (401)
Request parameters
Parameter Style Type Description
security_group plain xsd:dict

A security_group object.

name plain xsd:string

A symbolic name for the security group. Not required to be unique.

description (Optional) plain xsd:string

Describes the security group.

tenant_id (Optional) plain csapi:uuid

The ID of the tenant who owns the security group. Only administrative users can specify a tenant ID other than their own.

Response parameters
Parameter Style Type Description
security_group plain xsd:dict

A security_group object.

description plain xsd:string

The security group description.

id plain csapi:uuid

The UUID for the security group.

name plain xsd:string

The security group name.

security_group_rules plain xsd:dict

Security group rules.

direction plain xsd:string

Ingress or egress: the direction in which the security group rule is applied. For a compute instance, an ingress security group rule is applied to incoming (ingress) traffic for that instance. An egress rule is applied to traffic leaving the instance.

ethertype plain xsd:string

Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.

id plain csapi:uuid

The UUID of the security group rule.

port_range_max plain xsd:int

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.

port_range_min plain xsd:int

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.

protocol plain xsd:string

The protocol that is matched by the security group rule. Valid values are null, tcp, udp, and icmp.

remote_group_id plain csapi:uuid

The remote group ID to be associated with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body.

remote_ip_prefix plain xsd:string

The remote IP prefix to be associated with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body. This attribute value matches the specified IP prefix as the source IP address of the IP packet.

security_group_id plain csapi:uuid

The ID of the security group.

tenant_id plain csapi:uuid

The ID of the tenant who owns the security group rule. Only administrative users can specify a tenant ID other than their own.

{
    "security_group": {
        "name": "new-webservers",
        "description": "security group for webservers"
    }
}
{
    "security_group": {
        "description": "security group for webservers",
        "id": "2076db17-a522-4506-91de-c6dd8e837028",
        "name": "new-webservers",
        "security_group_rules": [
            {
                "direction": "egress",
                "ethertype": "IPv4",
                "id": "38ce2d8e-e8f1-48bd-83c2-d33cb9f50c3d",
                "port_range_max": null,
                "port_range_min": null,
                "protocol": null,
                "remote_group_id": null,
                "remote_ip_prefix": null,
                "security_group_id": "2076db17-a522-4506-91de-c6dd8e837028",
                "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550"
            },
            {
                "direction": "egress",
                "ethertype": "IPv6",
                "id": "565b9502-12de-4ffd-91e9-68885cff6ae1",
                "port_range_max": null,
                "port_range_min": null,
                "protocol": null,
                "remote_group_id": null,
                "remote_ip_prefix": null,
                "security_group_id": "2076db17-a522-4506-91de-c6dd8e837028",
                "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550"
            }
        ],
        "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550"
    }
}
GET
/v2.0/security-groups/​{security_group_id}​
Show security group

Shows details for a specified security group.

 

This operation returns a response body that contains the description, name, ID, and security group rules associated with the specified security group and tenant ID.

Normal response codes
200
Error response codes
unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
security_group_id URI csapi:uuid The unique identifier of the security group.
verbose (Optional) query xsd:bool

Show detailed information.

fields (Optional) query xsd:string

The fields to be returned by server.

Response parameters
Parameter Style Type Description
security_group plain xsd:dict

A security_group object.

description plain xsd:string

The security group description.

id plain csapi:uuid

The UUID for the security group.

name plain xsd:string

The security group name.

security_group_rules plain xsd:dict

Security group rules.

direction plain xsd:string

Ingress or egress: the direction in which the security group rule is applied. For a compute instance, an ingress security group rule is applied to incoming (ingress) traffic for that instance. An egress rule is applied to traffic leaving the instance.

ethertype plain xsd:string

Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.

id plain csapi:uuid

The UUID of the security group rule.

port_range_max plain xsd:int

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.

port_range_min plain xsd:int

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.

protocol plain xsd:string

The protocol that is matched by the security group rule. Valid values are null, tcp, udp, and icmp.

remote_group_id plain csapi:uuid

The remote group ID to be associated with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body.

remote_ip_prefix plain xsd:string

The remote IP prefix to be associated with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body. This attribute value matches the specified IP prefix as the source IP address of the IP packet.

security_group_id plain csapi:uuid

The ID of the security group.

tenant_id plain csapi:uuid

The ID of the tenant who owns the security group rule. Only administrative users can specify a tenant ID other than their own.

GET /v2.0/security-groups/85cc3048-abc3-43cc-89b3-377341426ac5
Accept: application/json
{
    "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 specified security group.

 
Normal response codes
200
Error response codes
computeFault (400, 500, …), serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), itemNotFound (404)
Request parameters
Parameter Style Type Description
security_group_id URI csapi:uuid The unique identifier of the security group.
name plain xsd:string

The security group name.

description (Optional) plain xsd:string

Security group description.

Response parameters
Parameter Style Type Description
security_group plain xsd:string

A security_group object.

description plain xsd:string

Security group description.

id plain csapi:UUID

The security group ID.

name plain xsd:string

The security group name.

tenant_id plain xsd:string

The tenant.

{
    "security_group": {
        "name": "mysecgroup",
        "description": "my security group"
    }
}
{
    "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.

Normal response codes
204
Error response codes
unauthorized (401), itemNotFound (404), conflict (409)
Request parameters
Parameter Style Type Description
security_group_id URI csapi:uuid The unique identifier of the security group.
DELETE /v2.0/security-groups/e470bdfc-4869-459b-a561-cb3377efae59
Content-Type: application/json
Accept: application/json
status: 204

Security group rules (security-group-rules)

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

GET
/v2.0/security-group-rules
List security group rules

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

 

The list provides the unique ID for each security group rule.

Normal response codes
200
Error response codes
unauthorized (401)
Response parameters
Parameter Style Type Description
security_group_rules plain xsd:dict

A security_group_rules object.

direction plain xsd:string

Ingress or egress: the direction in which the security group rule is applied. For a compute instance, an ingress security group rule is applied to incoming (ingress) traffic for that instance. An egress rule is applied to traffic leaving the instance.

ethertype plain xsd:string

Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.

id plain csapi:uuid

The UUID of the security group rule.

port_range_max plain xsd:int

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.

port_range_min plain xsd:int

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.

protocol plain xsd:string

The protocol that is matched by the security group rule. Valid values are null, tcp, udp, and icmp.

remote_group_id plain csapi:uuid

The remote group ID to be associated with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body.

remote_ip_prefix plain xsd:string

The remote IP prefix to be associated with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body. This attribute value matches the specified IP prefix as the source IP address of the IP packet.

security_group_id plain csapi:uuid

The ID of the security group.

tenant_id plain csapi:uuid

The ID of the tenant who owns the security group rule. Only administrative users can specify a tenant ID other than their own.

GET /v2.0/security-group-rules/
Accept: application/json
{
    "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.

 
Normal response codes
201
Error response codes
badRequest (400), unauthorized (401), itemNotFound (404), conflict (409)
Request parameters
Parameter Style Type Description
security_group_rule plain xsd:dict

A security_group_rule object.

direction plain xsd:string

Ingress or egress: The direction in which the security group rule is applied. For a compute instance, an ingress security group rule is applied to incoming (ingress) traffic for that instance. An egress rule is applied to traffic leaving the instance.

ethertype (Optional) plain xsd:string

Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.

security_group_id plain csapi:uuid

The security group ID to associate with this security group rule.

port_range_min (Optional) plain xsd:int

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.

port_range_max (Optional) plain xsd:int

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.

protocol (Optional) plain xsd:string

The protocol that is matched by the security group rule. Valid values are null, tcp, udp, and icmp.

remote_group_id (Optional) plain csapi:uuid

The remote group ID to be associated with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body.

remote_ip_prefix (Optional) plain csapi:uuid

The remote IP prefix to be associated with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body. This attribute matches the specified IP prefix as the source IP address of the IP packet.

Response parameters
Parameter Style Type Description
security_group_rule plain xsd:dict

A security_group_rule object.

direction plain xsd:string

Ingress or egress: the direction in which the security group rule is applied. For a compute instance, an ingress security group rule is applied to incoming (ingress) traffic for that instance. An egress rule is applied to traffic leaving the instance.

ethertype plain xsd:string

Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.

id plain csapi:uuid

The UUID of the security group rule.

port_range_max plain xsd:int

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.

port_range_min plain xsd:int

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.

protocol plain xsd:string

The protocol that is matched by the security group rule. Valid values are null, tcp, udp, and icmp.

remote_group_id plain csapi:uuid

The remote group ID to be associated with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body.

remote_ip_prefix plain xsd:string

The remote IP prefix to be associated with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body. This attribute value matches the specified IP prefix as the source IP address of the IP packet.

security_group_id plain csapi:uuid

The ID of the security group.

tenant_id plain csapi:uuid

The ID of the tenant who owns the security group rule. Only administrative users can specify a tenant ID other than their own.

{
    "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"
    }
}
{
    "security_group_rule": {
        "direction": "ingress",
        "ethertype": "IPv4",
        "id": "2bc0accf-312e-429a-956e-e4407625eb62",
        "port_range_max": 80,
        "port_range_min": 80,
        "protocol": "tcp",
        "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
        "remote_ip_prefix": null,
        "security_group_id": "a7734e61-b545-452d-a3cd-0189cbd9747a",
        "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550"
    }
}
GET
/v2.0/security-group-rules/​{rules-security-groups-id}​
Show security group rule

Shows detailed information for a specified security group rule.

 

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

Normal response codes
200
Error response codes
unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
rules-security-groups-id URI csapi:uuid The unique identifier of the security group rule.
Response parameters
Parameter Style Type Description
security_group_rule plain xsd:dict

A security_group_rule object.

direction plain xsd:string

Ingress or egress: the direction in which the security group rule is applied. For a compute instance, an ingress security group rule is applied to incoming (ingress) traffic for that instance. An egress rule is applied to traffic leaving the instance.

ethertype plain xsd:string

Must be IPv4 or IPv6, and addresses represented in CIDR must match the ingress or egress rules.

id plain csapi:uuid

The UUID of the security group rule.

port_range_max plain xsd:int

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.

port_range_min plain xsd:int

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.

protocol plain xsd:string

The protocol that is matched by the security group rule. Valid values are null, tcp, udp, and icmp.

remote_group_id plain csapi:uuid

The remote group ID to be associated with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body.

remote_ip_prefix plain xsd:string

The remote IP prefix to be associated with this security group rule. You can specify either the remote_group_id or remote_ip_prefix attribute in the request body. This attribute value matches the specified IP prefix as the source IP address of the IP packet.

security_group_id plain csapi:uuid

The ID of the security group.

tenant_id plain csapi:uuid

The ID of the tenant who owns the security group rule. Only administrative users can specify a tenant ID other than their own.

GET /v2.0/security-group-rules/ 3c0e45ff-adaf-4124-b083-bf390e5482ff
Accept: application/json
{
    "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/​{rules-security-groups-id}​
Delete security group rule

Deletes a specified rule from an OpenStack Networking security group.

 
Normal response codes
204
Error response codes
unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
rules-security-groups-id URI csapi:uuid The unique identifier of the security group rule.
DELETE /v2.0/security-group-rules/fc3c327a-b5b5-4cd3-9577-52893289ce08
Content-Type: application/json
Accept: application/json
status: 204

Layer-3 networking

Routes packets between subnets, forwards packets from internal networks to external ones, and accesses instances from external networks through floating IPs.

This extension introduces these resources:

  • router. A logical entity for forwarding packets across internal subnets and NATting them on external networks through an appropriate external gateway.

  • floatingip. An external IP address that is mapped to a port that is attached to an internal network.

GET
/v2.0/routers
List routers

Lists logical routers that are accessible to the tenant who submits the request.

 

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

This example request lists routers in JSON format:

GET /v2.0/routers
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
unauthorized (401)
Response parameters
Parameter Style Type Description
status plain xsd:string

The router status.

external_gateway_info plain xsd:dict

The external gateway parameters, which include the network_id and external_fixed_ips parameters.

external_fixed_ips plain xsd:dict

The IP address parameters.

name plain xsd:string

The router name.

admin_state_up plain xsd:bool

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

tenant_id plain csapi:uuid

The tenant ID.

distributed (Optional) plain xsd:bool

If true, indicates a distributed router.

routes plain xsd:list

The extra routes configuration for L3 router.

ha (Optional) plain xsd:bool

If true, indicates a highly-available router.

id plain csapi:uuid

The router ID.

{
    "routers": [
        {
            "status": "ACTIVE",
            "external_gateway_info": null,
            "name": "second_routers",
            "admin_state_up": true,
            "tenant_id": "6b96ff0cb17a4b859e1e575d221683d3",
            "routes": [],
            "id": "7177abc4-5ae9-4bb7-b0d4-89e94a4abf3b"
        },
        {
            "status": "ACTIVE",
            "external_gateway_info": {
                "network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8",
                "external_fixed_ips": [
                    {
                        "subnet_id": "255.255.255.0",
                        "ip": "192.168.10.2"
                    }
                ]
            },
            "name": "router1",
            "admin_state_up": true,
            "tenant_id": "33a40233088643acb66ff6eb0ebea679",
            "routes": [],
            "id": "a9254bdb-2613-4a13-ac4c-adc581fba50d"
        }
    ]
}

This operation does not accept a request body.

POST
/v2.0/routers
Create router

Creates a logical router.

 

This operation creates a new logical router. When it is created, a logical router does not have any internal interface; it is not associated to 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 extended field router:external set to true. To specify an external gateway, the identifier of the external network must be passed in the external_gateway_info attribute in the request body, as follows:

{
   "router": {
      "external_gateway_info": {
         "network_id": "8ca37218-28ff-41cb-9b10-039601ea7e6b"
      }
   }
}
Normal response codes
201
Error response codes
badRequest (400), unauthorized (401)
Request parameters
Parameter Style Type Description
router plain xsd:string

A router object.

name (Optional) plain xsd:string

The router name.

admin_state_up (Optional) plain xsd:bool

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

external_fixed_ips (Optional) plain xsd:dict

The IP address parameters.

Response parameters
Parameter Style Type Description
router plain xsd:string

A router object.

status plain xsd:string

The router status.

external_gateway_info plain xsd:dict

The external gateway parameters, which include the network_id and external_fixed_ips parameters.

external_fixed_ips plain xsd:dict

The IP address parameters.

name plain xsd:string

The router name.

admin_state_up plain xsd:bool

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

tenant_id plain csapi:uuid

The tenant ID.

routes plain xsd:list

The extra routes configuration for L3 router.

id plain csapi:uuid

The router ID.

{
    "router": {
        "name": "another_router",
        "external_gateway_info": {
            "network_id": "8ca37218-28ff-41cb-9b10-039601ea7e6b",
            "external_fixed_ips": [
                {
                    "subnet_id": "255.255.255.0",
                    "ip": "192.168.10.1"
                }
            ]
        },
        "admin_state_up": true
    }
}
{
    "router": {
        "status": "ACTIVE",
        "external_gateway_info": {
            "network_id": "8ca37218-28ff-41cb-9b10-039601ea7e6b",
            "external_fixed_ips": [
                {
                    "subnet_id": "255.255.255.0",
                    "ip": "192.168.10.2"
                }
            ]
        },
        "name": "another_router",
        "admin_state_up": true,
        "tenant_id": "6b96ff0cb17a4b859e1e575d221683d3",
        "routes": [],
        "id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e"
    }
}
GET
/v2.0/routers/​{router_id}​
Show router details

Shows details for a specified router.

 

This example request shows details for a router in JSON format:

GET /v2.0/routers/{router_id}
Accept: application/json

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
unauthorized (401), forbidden (403), itemNotFound (404)
Request parameters
Parameter Style Type Description
router_id URI csapi:UUID

The UUID of the router.

Response parameters
Parameter Style Type Description
router plain xsd:string

A router object.

status plain xsd:string

The router status.

external_gateway_info plain xsd:dict

The external gateway parameters, which include the network_id and external_fixed_ips parameters.

external_fixed_ips plain xsd:dict

The IP address parameters.

name plain xsd:string

The router name.

admin_state_up plain xsd:bool

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

tenant_id plain csapi:uuid

The tenant ID.

distributed (Optional) plain xsd:bool

If true, indicates a distributed router.

routes plain xsd:list

The extra routes configuration for L3 router.

ha (Optional) plain xsd:bool

If true, indicates a highly-available router.

id plain csapi:uuid

The router ID.

{
    "router": {
        "status": "ACTIVE",
        "external_gateway_info": {
            "network_id": "85d76829-6415-48ff-9c63-5c5ca8c61ac6",
            "external_fixed_ips": [
                {
                    "subnet_id": "255.255.255.0",
                    "ip": "192.168.10.2"
                }
            ]
        },
        "name": "router1",
        "admin_state_up": true,
        "tenant_id": "d6554fe62e2f41efbb6e026fad5c1542",
        "routes": [],
        "id": "a07eea83-7710-4860-931b-5fe220fae533"
    }
}

This operation does not accept a request body.

PUT
/v2.0/routers/​{router_id}​
Update router

Updates a logical router.

 

You can update the name, administrative state, and the external gateway. For more information about how to set the external gateway for a router, see the create router operation. This operation does not enable the update of router interfaces. To update a router, use the add router interface and remove router interface operations.

This example updates the external gateway information for a router:

PUT /v2.0/routers/{router_id}
Accept: application/json
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
router_id URI csapi:UUID

The UUID of the router.

router plain xsd:string

A router object.

external_gateway_info (Optional) plain xsd:dict

The external gateway parameters, which include the network_id and external_fixed_ips parameters.

name (Optional) plain xsd:string

The router name.

admin_state_up (Optional) plain xsd:bool

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

external_fixed_ips (Optional) plain xsd:dict

The IP address parameters.

Response parameters
Parameter Style Type Description
router plain xsd:string

A router object.

status plain xsd:string

The router status.

external_gateway_info plain xsd:dict

The external gateway parameters, which include the network_id and external_fixed_ips parameters.

external_fixed_ips plain xsd:dict

The IP address parameters.

name plain xsd:string

The router name.

admin_state_up plain xsd:bool

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

tenant_id plain csapi:uuid

The tenant ID.

routes plain xsd:list

The extra routes configuration for L3 router.

id plain csapi:uuid

The router ID.

{
    "router": {
        "external_gateway_info": {
            "network_id": "8ca37218-28ff-41cb-9b10-039601ea7e6b",
            "external_fixed_ips": [
                {
                    "subnet_id": "255.255.255.0",
                    "ip": "192.168.10.1"
                }
            ]
        }
    }
}
{
    "router": {
        "status": "ACTIVE",
        "external_gateway_info": {
            "network_id": "8ca37218-28ff-41cb-9b10-039601ea7e6b",
            "external_fixed_ips": [
                {
                    "subnet_id": "255.255.255.0",
                    "ip": "192.168.10.2"
                }
            ]
        },
        "name": "another_router",
        "admin_state_up": true,
        "tenant_id": "6b96ff0cb17a4b859e1e575d221683d3",
        "routes": [],
        "id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e"
    }
}
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.

This example deletes a router:

DELETE /v2.0/routers/{router_id}
Accept: application/json
Normal response codes
204
Error response codes
unauthorized (401), itemNotFound (404), conflict (409)
Request parameters
Parameter Style Type Description
router_id URI csapi:UUID

The UUID of the router.

This operation does not accept a request body and does not return a response body.

PUT
/v2.0/routers/​{router_id}​/add_router_interface
Add interface to router

Adds an internal interface to a logical router.

 

Attaches a subnet to an internal router interface.

Specify a subnet ID or port ID in the request body:

  • Subnet ID. The gateway IP address for the subnet is used to create the router interface.

  • Port ID. The IP address associated with the port is used to create the router interface.

If you specify both IDs, the operation returns a 400 Bad Request error.

If the port is already used, the operation returns a 409 Conflict error.

The port ID that is returned by this operation can be either:

  • The same ID that is passed in the request body.

  • The ID of a port that is created by this operation to attach the specified subnet to the router.

After you run this operation:

  • The device ID of this port is set to the router ID.

  • The device_owner attribute is set to network:router_interface.

Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), itemNotFound (404), conflict (409)
Request parameters
Parameter Style Type Description
router_id URI csapi:UUID

The UUID of the router.

subnet_id plain csapi:uuid

The subnet ID.

port_id plain csapi:uuid

The port ID.

Response parameters
Parameter Style Type Description
subnet_id plain csapi:uuid

The subnet ID.

tenant_id plain csapi:uuid

The tenant ID.

port_id plain csapi:uuid

The port ID.

id plain csapi:uuid

The router ID.

{
    "subnet_id": "a2f1f29d-571b-4533-907f-5803ab96ead1"
}
{
    "subnet_id": "a2f1f29d-571b-4533-907f-5803ab96ead1",
    "tenant_id": "6ba032e4730d42e2ad928f430f5da33e",
    "port_id": "3a44f4e5-1694-493a-a1fb-393881c673a4",
    "id": "b0294d7e-7da4-4202-9882-2ab1de9dabc0"
}
PUT
/v2.0/routers/​{router_id}​/remove_router_interface
Remove interface from router

Removes an internal interface from a logical router.

 

This operation removes an internal router interface, which detaches a subnet from the router. You must specify either a subnet ID or port ID in the request body; this value is used to identify the router interface to remove.

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 specified by the port ID. Otherwise, the operation returns a 409 Conflict error. The response contains information about the affected router and interface.

The operation returns a 404 Not Found if the router or the subnet and port do not exist or are not visible to you. As a consequence of this operation, the port connecting the router with the subnet is removed from the subnet for the network.

This example removes an interface from a router:

PUT /v2.0/routers/{router_id}/remove_router_interface
Accept: application/json
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), itemNotFound (404), conflict (409)
Request parameters
Parameter Style Type Description
router_id URI csapi:UUID

The UUID of the router.

subnet_id plain csapi:uuid

The subnet ID.

port_id plain csapi:uuid

The port ID.

Response parameters
Parameter Style Type Description
id plain csapi:uuid

The router ID.

tenant_id plain csapi:uuid

The tenant ID.

port_id plain csapi:uuid

The port ID.

subnet_id plain csapi:uuid

The subnet ID.

{
    "subnet_id": "a2f1f29d-571b-4533-907f-5803ab96ead1"
}
{
    "id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e",
    "tenant_id": "2f245a7b-796b-4f26-9cf9-9e82d248fda7",
    "port_id": "3a44f4e5-1694-493a-a1fb-393881c673a4",
    "subnet_id": "a2f1f29d-571b-4533-907f-5803ab96ead1"
}
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
unauthorized (401)
Response parameters
Parameter Style Type Description
floatingips plain xsd:dict

A floatingips object.

router_id plain csapi:uuid

The router ID.

tenant_id plain csapi:uuid

The tenant ID.

floating_network_id plain csapi:uuid

The ID of the network associated with the floating IP.

fixed_ip_address plain xsd:string

The fixed IP address associated with the floating IP.

floating_ip_address plain xsd:string

The floating IP address.

port_id plain csapi:uuid

The port ID.

id plain csapi:uuid

The ID of the floating IP address.

status plain xsd:string

The floating IP status.

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

This operation does not accept a request body.

POST
/v2.0/floatingips
Create floating IP

Creates a floating IP, and, if you specify port information, associates the floating IP with an internal port.

 

To associate the floating IP with an internal port, specify the port ID attribute in the request body. If you do not specify a port ID in the request, you can issue a PUT request instead of a POST request.

Default policy settings enable only administrative users to set floating IP addresses and some non-administrative users might require a floating IP address. If you do not specify a floating IP address in the request, the API 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 specific fixed IP address with the floating IP address.

You can create floating IPs on external networks only.

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 specified network is not external, such as router:external=False.

    • The specified 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 specified fixed IP address is not valid.

  • 401 The operation is not authorized.

  • 404 The specified port ID 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 specified fixed IP address are already associated with another floating IP.

Normal response codes
201
Error response codes
badRequest (400), unauthorized (401), itemNotFound (404), conflict (409)
Request parameters
Parameter Style Type Description
floatingip plain xsd:string

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 (Optional) plain csapi:uuid

The tenant ID. Only administrative users can specify a tenant ID other than their own.

floating_network_id plain csapi:uuid

The ID of the network associated with the floating IP.

fixed_ip_address (Optional) plain xsd:string

The fixed IP address associated with the floating IP. If you intend to associate the floating IP with a fixed IP at creation time, then you must indicate the identifier of the internal port. If an internal port has multiple associated IP addresses, the service chooses the first IP unless you explicitly specify the parameter fixed_ip_address to select a specific IP.

floating_ip_address (Optional) plain xsd:string

The floating IP address.

port_id (Optional) plain csapi:uuid

The port ID.

Response parameters
Parameter Style Type Description
floatingip plain xsd:string

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.

fixed_ip_address plain xsd:string

The fixed IP address associated with the floating IP.

floating_ip_address plain xsd:string

The floating IP address.

floating_network_id plain csapi:uuid

The ID of the network associated with the floating IP.

id plain csapi:uuid

The ID of the floating IP address.

port_id plain csapi:uuid

The port ID.

router_id plain csapi:uuid

The router ID.

status plain xsd:string

The floating IP status.

tenant_id plain csapi:uuid

The tenant ID.

{
    "floatingip": {
        "floating_network_id": "376da547-b977-4cfe-9cba-275c80debf57",
        "port_id": "ce705c24-c1ef-408a-bda3-7bbd946164ab"
    }
}
{
    "floatingip": {
        "fixed_ip_address": "10.0.0.3",
        "floating_ip_address": "172.24.4.228",
        "floating_network_id": "376da547-b977-4cfe-9cba-275c80debf57",
        "id": "2f245a7b-796b-4f26-9cf9-9e82d248fda7",
        "port_id": "ce705c24-c1ef-408a-bda3-7bbd946164ab",
        "router_id": "d23abc8d-2991-4a55-ba98-2aaea84cc72f",
        "status": "ACTIVE",
        "tenant_id": "4969c491a3c74ee4af974e6d800c62de"
    }
}
GET
/v2.0/floatingips/​{floatingip_id}​
Show floating IP details

Shows details for a specified 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
unauthorized (401), forbidden (403), itemNotFound (404)
Request parameters
Parameter Style Type Description
floatingip_id URI csapi:UUID

The UUID of the floating IP.

Response parameters
Parameter Style Type Description
floatingip plain xsd:string

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.

floating_network_id plain csapi:uuid

The ID of the network associated with the floating IP.

router_id plain csapi:uuid

The router ID.

fixed_ip_address plain xsd:string

The fixed IP address associated with the floating IP.

floating_ip_address plain xsd:string

The floating IP address.

tenant_id plain csapi:uuid

The tenant ID.

status plain xsd:string

The floating IP status.

port_id plain csapi:uuid

The port ID.

id plain csapi:uuid

The ID of the floating IP address.

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

This operation does not accept a request body.

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
badRequest (400), unauthorized (401), itemNotFound (404), conflict (409)
Request parameters
Parameter Style Type Description
floatingip_id URI csapi:UUID

The UUID of the floating IP.

port_id plain csapi:uuid

The port ID.

Response parameters
Parameter Style Type Description
floatingip plain xsd:string

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.

floating_network_id plain csapi:uuid

The ID of the network associated with the floating IP.

router_id plain csapi:uuid

The router ID.

fixed_ip_address plain xsd:string

The fixed IP address associated with the floating IP.

floating_ip_address plain xsd:string

The floating IP address.

tenant_id plain csapi:uuid

The tenant ID.

status plain xsd:string

The floating IP status.

port_id plain csapi:uuid

The port ID.

id plain csapi:uuid

The ID of the floating IP address.

{
    "floatingip": {
        "port_id": "fc861431-0e6c-4842-a0ed-e2363f9bc3a8"
    }
}
{
    "floatingip": {
        "port_id": null
    }
}
{
    "floatingip": {
        "floating_network_id": "376da547-b977-4cfe-9cba-275c80debf57",
        "router_id": "d23abc8d-2991-4a55-ba98-2aaea84cc72f",
        "fixed_ip_address": "10.0.0.4",
        "floating_ip_address": "172.24.4.228",
        "tenant_id": "4969c491a3c74ee4af974e6d800c62de",
        "status": "ACTIVE",
        "port_id": "fc861431-0e6c-4842-a0ed-e2363f9bc3a8",
        "id": "2f245a7b-796b-4f26-9cf9-9e82d248fda7"
    }
}
{
    "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
Normal response codes
204
Error response codes
unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
floatingip_id URI csapi:UUID

The UUID of the floating IP.

This operation does not accept a request body and does not return a response body.

Metering labels and 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 specified tenant.

 

The list includes the unique ID for each metering labels.

This operation does not require a request body.

This operation returns a response body.

Normal response codes
200
Error response codes
unauthorized (401)
GET /v2.0/metering/metering-labels HTTP/1.1
Host: controlnode:9696
User-Agent: python-neutronclient
Content-Type: application/json
Accept: application/json
X-Auth-Token: c52a1b304fec4ca0ac85dc1741eec6e2
{
    "metering_labels": [
        {
            "tenant_id": "45345b0ee1ea477fac0f541b2cb79cd4",
            "description": "label1 description",
            "name": "label1",
            "id": "a6700594-5b7a-4105-8bfe-723b346ce866"
        },
        {
            "tenant_id": "45345b0ee1ea477fac0f541b2cb79cd4",
            "description": "label2 description",
            "name": "label2",
            "id": "e131d186-b02d-4c0b-83d5-0c0725c4f812"
        }
    ]
}
POST
/v2.0/metering/metering-labels
Create metering label

Creates a l3 metering label.

 

This operation requires a request body.

The following table describes the required and optional attributes in the request body:

Normal response codes
201
Error response codes
badRequest (400), unauthorized (401)
Request parameters
Parameter Style Type Description
metering_label plain xsd:dict

The metering label object.

name plain xsd:string

The name of the metering label.

description (Optional) plain xsd:string

Description for the metering label.

Response parameters
Parameter Style Type Description
metering_label plain xsd:dict

The metering label object.

tenant_id plain csapi:uuid

The tenant ID for the specified metering label.

description plain xsd:string

Description for the metering label.

name plain xsd:string

The name of the metering label.

id plain csapi:uuid

The metering label ID.

{
    "metering_label": {
        "name": "label1",
        "description": "description of label1"
    }
}
{
    "metering_label": {
        "tenant_id": "45345b0ee1ea477fac0f541b2cb79cd4",
        "description": "description of label1",
        "name": "label1",
        "id": "bc91b832-8465-40a7-a5d8-ba87de442266"
    }
}
GET
/v2.0/metering/metering-labels/​{metering_label_id}​
Show metering label

Shows information for a specified metering label.

 

This operation does not require a request body.

This operation returns a response body that contains the description, name, ID.

Normal response codes
200
Error response codes
unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
metering_label_id URI csapi:uuid

The unique identifier of the metering label.

GET /v2.0/metering/metering-labels/a6700594-5b7a-4105-8bfe-723b346ce866 HTTP/1.1
Host: controlnode:9696
User-Agent: python-neutronclient
Content-Type: application/json
Accept: application/json
X-Auth-Token: c52a1b304fec4ca0ac85dc1741eec6e2
{
    "metering_label": {
        "tenant_id": "45345b0ee1ea477fac0f541b2cb79cd4",
        "description": "label1 description",
        "name": "label1",
        "id": "a6700594-5b7a-4105-8bfe-723b346ce866"
    }
}
DELETE
/v2.0/metering/metering-labels/​{metering_label_id}​
Delete metering label

Deletes a l3 metering label.

 

This operation deletes a l3 metering label.

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

Normal response codes
204
Error response codes
unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
metering_label_id URI csapi:uuid

The unique identifier of the metering label.

DELETE /v2.0/metering/metering-labels/a6700594-5b7a-4105-8bfe-723b346ce866 HTTP/1.1
Host: controlnode:9696
User-Agent: python-neutronclient
Content-Type: application/json
Accept: application/json
X-Auth-Token: c52a1b304fec4ca0ac85dc1741eec6e2
status: 204
GET
/v2.0/metering/metering-label-rules
List metering label rules

Lists a summary of all l3 metering label rules belonging to the specified tenant.

 

The list provides the unique ID for each metering label rule.

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

Normal response codes
200
Error response codes
unauthorized (401)
GET /v2.0/metering/metering-label-rules HTTP/1.1
Host: controlnode:9696
User-Agent: python-neutronclient
Content-Type: application/json
Accept: application/json
X-Auth-Token: c52a1b304fec4ca0ac85dc1741eec6e2
{
    "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 a l3 metering label rule.

 

This operation requires a request body.

This operation returns a response body.

Normal response codes
201
Error response codes
badRequest (400), unauthorized (401), itemNotFound (404), buildInProgress (409)
Request parameters
Parameter Style Type Description
metering_label_rule plain xsd:dict

The metering label rule object.

direction plain xsd:string

Ingress or egress, which is the direction in which the metering rule is applied.

metering_label_id plain csapi:uuid

The metering label ID to associate with this metering rule.

excluded (Optional) plain xsd:boolean

Indicates whether to count the traffic of a specific IP address with the remote_ip_prefix value. Default is False.

remote_ip_prefix (Optional) plain xsd:string

The remote IP prefix to be associated with this metering rule packet.

Response parameters
Parameter Style Type Description
metering_label_rule plain xsd:dict

The metering label rule object.

remote_ip_prefix plain xsd:string

The remote IP prefix to be associated with this metering rule packet.

direction plain xsd:string

Ingress or egress, which is the direction in which the metering rule is applied.

metering_label_id plain csapi:uuid

The metering label ID to associate with this metering rule.

id plain csapi:uuid

The ID for the specified metering label rule.

excluded plain xsd:boolean

Indicates whether to count the traffic of a specific IP address with the remote_ip_prefix value. Default is False.

{
    "metering_label_rule": {
        "remote_ip_prefix": "10.0.1.0/24",
        "direction": "ingress",
        "metering_label_id": "e131d186-b02d-4c0b-83d5-0c0725c4f812"
    }
}
{
    "metering_label_rule": {
        "remote_ip_prefix": "10.0.1.0/24",
        "direction": "ingress",
        "metering_label_id": "e131d186-b02d-4c0b-83d5-0c0725c4f812",
        "id": "00e13b58-b4f2-4579-9c9c-7ac94615f9ae",
        "excluded": false
    }
}
GET
/v2.0/metering/metering-label-rules/​{metering-label-rule-id}​
Show metering label rule

Shows detailed information for a specified metering label rule.

 

This operation does not require a request body.

This operation returns a response body, which contains the following information about the metering label rule:

  • direction. Either ingress or egress.

  • excluded. Either True or False.

  • The ID for the specified 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
unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
metering-label-rule-id URI csapi:uuid

The unique identifier of metering label rule.

GET /v2.0/metering/metering-label-rules/9536641a-7d14-4dc5-afaf-93a973ce0eb8 HTTP/1.1
Host: controlnode:9696
User-Agent: python-neutronclient
Content-Type: application/json
Accept: application/json
X-Auth-Token: c52a1b304fec4ca0ac85dc1741eec6e2
{
    "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 a specified l3 metering label rule.

 

This operation does not require a request body.

This operation does not return a response body.

Normal response codes
204
Error response codes
unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
metering-label-rule-id URI csapi:uuid

The unique identifier of metering label rule.

DELETE /v2.0/metering/metering-labels/37b31179-71ee-4f0a-b130-0eeb28e7ede7 HTTP/1.1
Host: controlnode:9696
User-Agent: python-neutronclient
Content-Type: application/json
Accept: application/json
X-Auth-Token: c52a1b304fec4ca0ac85dc1741eec6e2
status: 204

Load-Balancer-as-a-Service (LBaaS) 1.0 (STABLE)

The LBaaS version 1.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 virtual IP addresses (VIPs), pools, members of a pool, health monitors associated with a pool, and view status of a resource.

Load balancer statuses
Status Description

ACTIVE

Resource is ready and active.

PENDING_CREATE

Resource is being created.

PENDING_UPDATE

Resource is being updated.

PENDING_DELETE

Resource is pending deletion.

INACTIVE

Resource was created but is not active.

ERROR

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/vips
List VIPs

Lists VIPs.

 
Normal response codes
200
Error response codes
unauthorized (401), Internal-server-error (500), serviceUnavailable (503)
Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the VIP.

tenant_id plain csapi:uuid

The ID of the tenant who owns the VIP. Only administrative users can specify a tenant ID other than their own.

name plain xsd:string

Human-readable name for the VIP. Does not have to be unique.

description plain xsd:string

Human-readable description for the VIP.

subnet_id plain csapi:uuid

The ID of the subnet on which to allocate the VIP address.

port_id plain csapi:uuid

The ID of the VIP port.

address plain xsd:ip

The IP address of the VIP.

protocol plain xsd:string

The protocol of the VIP address. A valid value is TCP, HTTP, or HTTPS.

protocol_port plain xsd:int

The port on which to listen to client traffic that is associated with the VIP address. A valid value is from 0 to 65535.

pool_id plain csapi:uuid

The ID of the pool with which the VIP is associated.

session_persistence plain xsd:dict

Session persistence parameters for the VIP. Omit the session_persistence parameter to prevent session persistence. When no session persistence is used, the session_persistence parameter does not appear in the API response. To clear session persistence for the VIP, set the session_persistence parameter to null in a VIP update request.

connection_limit plain xsd:int

The maximum number of connections allowed for the VIP. Default is -1, meaning no limit.

admin_state_up plain xsd:boolean

The administrative state of the VIP. A valid value is true (UP) or false (DOWN).

status plain xsd:string

The status of the VIP. Indicates whether the VIP is operational.

{
    "vips": [
        {
            "status": "ACTIVE",
            "protocol": "HTTP",
            "description": "",
            "admin_state_up": true,
            "subnet_id": "8032909d-47a1-4715-90af-5153ffe39861",
            "tenant_id": "83657cfcdfe44cd5920adaf26c48ceea",
            "connection_limit": 1000,
            "pool_id": "72741b06-df4d-4715-b142-276b6bce75ab",
            "session_persistence": {
                "cookie_name": "MyAppCookie",
                "type": "APP_COOKIE"
            },
            "address": "10.0.0.10",
            "protocol_port": 80,
            "port_id": "b5a743d6-056b-468b-862d-fb13a9aa694e",
            "id": "4ec89087-d057-4e2c-911f-60a3b47ee304",
            "name": "my-vip"
        }
    ]
}

This operation does not accept a request body.

POST
/v2.0/lb/vips
Create a load balancer VIP

Creates a load balancer VIP.

 
Normal response codes
201
Error response codes
unauthorized (401), itemNotFound (404), conflict (409), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Request parameters
Parameter Style Type Description
tenant_id (Optional) plain csapi:uuid

The ID of the tenant who owns the VIP. Only administrative users can specify a tenant ID other than their own.

name (Optional) plain xsd:string

Human-readable name for the VIP. Does not have to be unique.

description (Optional) plain xsd:string

Human-readable description for the VIP.

subnet_id plain csapi:uuid

The ID of the subnet on which to allocate the VIP address.

address (Optional) plain xsd:ip

The IP address of the VIP.

protocol plain xsd:string

The protocol of the VIP address. A valid value is TCP, HTTP, or HTTPS.

protocol_port plain xsd:int

The port on which to listen to client traffic that is associated with the VIP address. A valid value is from 0 to 65535.

pool_id plain csapi:uuid

The ID of the pool with which the VIP is associated.

session_persistence (Optional) plain xsd:dict

Session persistence parameters for the VIP. Omit the session_persistence parameter to prevent session persistence. When no session persistence is used, the session_persistence parameter does not appear in the API response. To clear session persistence for the VIP, set the session_persistence parameter to null in a VIP update request.

connection_limit (Optional) plain xsd:int

The maximum number of connections allowed for the VIP. Value is -1 if the limit is not set.

admin_state_up (Optional) plain xsd:boolean

The administrative state of the VIP. A valid value is true (UP) or false (DOWN).

Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the VIP.

tenant_id plain csapi:uuid

The ID of the tenant who owns the VIP. Only administrative users can specify a tenant ID other than their own.

name plain xsd:string

Human-readable name for the VIP. Does not have to be unique.

description plain xsd:string

Human-readable description for the VIP.

subnet_id plain csapi:uuid

The ID of the subnet on which to allocate the VIP address.

port_id plain csapi:uuid

The ID of the VIP port.

address plain xsd:ip

The IP address of the VIP.

protocol plain xsd:string

The protocol of the VIP address. A valid value is TCP, HTTP, or HTTPS.

protocol_port plain xsd:int

The port on which to listen to client traffic that is associated with the VIP address. A valid value is from 0 to 65535.

pool_id plain csapi:uuid

The ID of the pool with which the VIP is associated.

session_persistence plain xsd:dict

Session persistence parameters for the VIP. Omit the session_persistence parameter to prevent session persistence. When no session persistence is used, the session_persistence parameter does not appear in the API response. To clear session persistence for the VIP, set the session_persistence parameter to null in a VIP update request.

connection_limit plain xsd:int

The maximum number of connections allowed for the VIP. Default is -1, meaning no limit.

admin_state_up plain xsd:boolean

The administrative state of the VIP. A valid value is true (UP) or false (DOWN).

status plain xsd:string

The status of the VIP. Indicates whether the VIP is operational.

{
    "vip": {
        "protocol": "HTTP",
        "name": "NewVip",
        "admin_state_up": true,
        "subnet_id": "8032909d-47a1-4715-90af-5153ffe39861",
        "pool_id": "61b1f87a-7a21-4ad3-9dda-7f81d249944f",
        "protocol_port": "80"
    }
}
{
    "vip": {
        "status": "PENDING_CREATE",
        "protocol": "HTTP",
        "description": "",
        "admin_state_up": true,
        "subnet_id": "8032909d-47a1-4715-90af-5153ffe39861",
        "tenant_id": "83657cfcdfe44cd5920adaf26c48ceea",
        "connection_limit": -1,
        "pool_id": "61b1f87a-7a21-4ad3-9dda-7f81d249944f",
        "address": "10.0.0.11",
        "protocol_port": 80,
        "port_id": "f7e6fe6a-b8b5-43a8-8215-73456b32e0f5",
        "id": "c987d2be-9a3c-4ac9-a046-e8716b1350e2",
        "name": "NewVip"
    }
}
GET
/v2.0/lb/vips/​{vip_id}​
Show VIP details

Shows details for a specified VIP.

 
Normal response codes
200
Error response codes
unauthorized (401), forbidden (403), itemNotFound (404), conflict (409), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Request parameters
Parameter Style Type Description
vip_id URI csapi:UUID The UUID for the VIP.
Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the VIP.

tenant_id plain csapi:uuid

The ID of the tenant who owns the VIP. Only administrative users can specify a tenant ID other than their own.

name plain xsd:string

Human-readable name for the VIP. Does not have to be unique.

description plain xsd:string

Human-readable description for the VIP.

subnet_id plain csapi:uuid

The ID of the subnet on which to allocate the VIP address.

port_id plain csapi:uuid

The ID of the VIP port.

address plain xsd:ip

The IP address of the VIP.

protocol plain xsd:string

The protocol of the VIP address. A valid value is TCP, HTTP, or HTTPS.

protocol_port plain xsd:int

The port on which to listen to client traffic that is associated with the VIP address. A valid value is from 0 to 65535.

pool_id plain csapi:uuid

The ID of the pool with which the VIP is associated.

session_persistence plain xsd:dict

Session persistence parameters for the VIP. Omit the session_persistence parameter to prevent session persistence. When no session persistence is used, the session_persistence parameter does not appear in the API response. To clear session persistence for the VIP, set the session_persistence parameter to null in a VIP update request.

connection_limit plain xsd:int

The maximum number of connections allowed for the VIP. Default is -1, meaning no limit.

admin_state_up plain xsd:boolean

The administrative state of the VIP. A valid value is true (UP) or false (DOWN).

status plain xsd:string

The status of the VIP. Indicates whether the VIP is operational.

{
    "vip": {
        "status": "ACTIVE",
        "protocol": "HTTP",
        "description": "",
        "admin_state_up": true,
        "subnet_id": "8032909d-47a1-4715-90af-5153ffe39861",
        "tenant_id": "83657cfcdfe44cd5920adaf26c48ceea",
        "connection_limit": 1000,
        "pool_id": "72741b06-df4d-4715-b142-276b6bce75ab",
        "session_persistence": {
            "cookie_name": "MyAppCookie",
            "type": "APP_COOKIE"
        },
        "address": "10.0.0.10",
        "protocol_port": 80,
        "port_id": "b5a743d6-056b-468b-862d-fb13a9aa694e",
        "id": "4ec89087-d057-4e2c-911f-60a3b47ee304",
        "name": "my-vip"
    }
}

This operation does not accept a request body.

PUT
/v2.0/lb/vips/​{vip_id}​
Update VIP

Updates a specified load balancer VIP.

 
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Request parameters
Parameter Style Type Description
vip_id URI csapi:UUID The UUID for the VIP.
name (Optional) plain xsd:string

Human-readable name for the VIP. Does not have to be unique.

description (Optional) plain xsd:string

Human-readable description for the VIP.

pool_id (Optional) plain csapi:uuid

The ID of the pool with which the VIP is associated.

session_persistence (Optional) plain xsd:dict

Session persistence parameters for the VIP. Omit the session_persistence parameter to prevent session persistence. When no session persistence is used, the session_persistence parameter does not appear in the API response. To clear session persistence for the VIP, set the session_persistence parameter to null in a VIP update request.

connection_limit (Optional) plain xsd:int

The maximum number of connections allowed for the VIP. Value is -1 if the limit is not set.

admin_state_up (Optional) plain xsd:boolean

The administrative state of the VIP. A valid value is true (UP) or false (DOWN).

Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the VIP.

tenant_id plain csapi:uuid

The ID of the tenant who owns the VIP. Only administrative users can specify a tenant ID other than their own.

name plain xsd:string

Human-readable name for the VIP. Does not have to be unique.

description plain xsd:string

Human-readable description for the VIP.

subnet_id plain csapi:uuid

The ID of the subnet on which to allocate the VIP address.

port_id plain csapi:uuid

The ID of the VIP port.

address plain xsd:ip

The IP address of the VIP.

protocol plain xsd:string

The protocol of the VIP address. A valid value is TCP, HTTP, or HTTPS.

protocol_port plain xsd:int

The port on which to listen to client traffic that is associated with the VIP address. A valid value is from 0 to 65535.

pool_id plain csapi:uuid

The ID of the pool with which the VIP is associated.

session_persistence plain xsd:dict

Session persistence parameters for the VIP. Omit the session_persistence parameter to prevent session persistence. When no session persistence is used, the session_persistence parameter does not appear in the API response. To clear session persistence for the VIP, set the session_persistence parameter to null in a VIP update request.

connection_limit plain xsd:int

The maximum number of connections allowed for the VIP. Default is -1, meaning no limit.

admin_state_up plain xsd:boolean

The administrative state of the VIP. A valid value is true (UP) or false (DOWN).

status plain xsd:string

The status of the VIP. Indicates whether the VIP is operational.

{
    "vip": {
        "connection_limit": "1000"
    }
}
{
    "vip": {
        "status": "PENDING_UPDATE",
        "protocol": "HTTP",
        "description": "",
        "admin_state_up": true,
        "subnet_id": "8032909d-47a1-4715-90af-5153ffe39861",
        "tenant_id": "83657cfcdfe44cd5920adaf26c48ceea",
        "connection_limit": 1000,
        "pool_id": "61b1f87a-7a21-4ad3-9dda-7f81d249944f",
        "address": "10.0.0.11",
        "protocol_port": 80,
        "port_id": "f7e6fe6a-b8b5-43a8-8215-73456b32e0f5",
        "id": "c987d2be-9a3c-4ac9-a046-e8716b1350e2",
        "name": "NewVip"
    }
}
DELETE
/v2.0/lb/vips/​{vip_id}​
Delete VIP

Deletes a specified load balancer VIP.

 
Normal response codes
204
Error response codes
badRequest (400), unauthorized (401), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Request parameters
Parameter Style Type Description
vip_id URI csapi:UUID The UUID for the VIP.

This operation does not accept a request body and does not return a response body.

GET
/v2.0/lb/healthmonitors
List health monitors

Lists health monitors.

 
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the VIP.

tenant_id plain csapi:uuid

The ID of the tenant who owns the VIP. Only administrative users can specify a tenant ID other than their own.

type plain xsd:string

The type of probe sent by the load balancer to verify the member state, which is PING, TCP, HTTP, or HTTPS.

delay plain xsd:int

The time, in seconds, between sending probes to members.

timeout plain xsd:int

The maximum number of seconds for a monitor to wait for a connection to be established before it times out. This value must be less than the delay value.

max_retries plain xsd:int

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) plain xsd:string

The HTTP method that the monitor uses for requests.

url_path (Optional) plain xsd:string

The HTTP path of the request sent by the monitor to test the health of a member. Must be a string beginning with a forward slash (/).

expected_codes (Optional) plain xsd:string

Expected HTTP codes for a passing HTTP(S) monitor.

admin_state_up (Optional) plain xsd:boolean

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

status plain xsd:string

The status of the health monitor. Indicates whether the health monitor is operational.

{
   "health_monitors":[
      {
         "admin_state_up":true,
         "tenant_id":"83657cfcdfe44cd5920adaf26c48ceea",
         "delay":10,
         "max_retries":1,
         "timeout":1,
         "type":"PING",
         "id":"466c8345-28d8-4f84-a246-e04380b0461d"
      },
      {
         "admin_state_up":true,
         "tenant_id":"83657cfcdfe44cd5920adaf26c48ceea",
         "delay":5,
         "expected_codes":"200",
         "max_retries":2,
         "http_method":"GET",
         "timeout":2,
         "url_path":"/",
         "type":"HTTP",
         "id":"5d4b5228-33b0-4e60-b225-9b727c1a20e7"
      }
   ]
}

This operation does not accept a request body.

POST
/v2.0/lb/healthmonitors
Create a load balancer health monitor

Creates a load balancer health monitor.

 
Normal response codes
201
Error response codes
badRequest (400), unauthorized (401), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Request parameters
Parameter Style Type Description
tenant_id plain csapi:uuid

The ID of the tenant who owns the VIP. Only administrative users can specify a tenant ID other than their own.

type plain xsd:string

The type of probe that is sent by the load balancer to verify the member state. A valid value is PING, TCP, HTTP, or HTTPS.

delay plain xsd:int

The time, in seconds, between sending probes to members.

timeout plain xsd:int

Time in seconds to timeout each probe.

max_retries plain xsd:int

Maximum consecutive health probe tries.

url_path (Optional) plain xsd:string

Path portion of URI that will be probed if type is HTTP(S).

expected_codes (Optional) plain xsd:string

Expected HTTP codes for a passing HTTP(S) monitor.

Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the VIP.

tenant_id plain csapi:uuid

The ID of the tenant who owns the VIP. Only administrative users can specify a tenant ID other than their own.

type plain xsd:string

The type of probe sent by the load balancer to verify the member state, which is PING, TCP, HTTP, or HTTPS.

delay plain xsd:int

The time, in seconds, between sending probes to members.

timeout plain xsd:int

The maximum number of seconds for a monitor to wait for a connection to be established before it times out. This value must be less than the delay value.

max_retries plain xsd:int

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) plain xsd:string

The HTTP method that the monitor uses for requests.

url_path (Optional) plain xsd:string

The HTTP path of the request sent by the monitor to test the health of a member. Must be a string beginning with a forward slash (/).

expected_codes (Optional) plain xsd:string

Expected HTTP codes for a passing HTTP(S) monitor.

admin_state_up (Optional) plain xsd:boolean

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

status plain xsd:string

The status of the health monitor. Indicates whether the health monitor is operational.

{
    "healthmonitor": {
        "admin_state_up": true,
        "delay": "1",
        "expected_codes": "200,201,202",
        "http_method": "GET",
        "max_retries": 5,
        "pool_id": "74aa2010-a59f-4d35-a436-60a6da882819",
        "timeout": 1,
        "type": "HTTP",
        "url_path": "/index.html"
    }
}
{
    "healthmonitor": {
        "admin_state_up": true,
        "delay": 1,
        "expected_codes": "200,201,202",
        "http_method": "GET",
        "id": "0a9ac99d-0a09-4b18-8499-a0796850279a",
        "max_retries": 5,
        "pools": [
            {
                "id": "74aa2010-a59f-4d35-a436-60a6da882819"
            }
        ],
        "tenant_id": "6f3584d5754048a18e30685362b88411",
        "timeout": 1,
        "type": "HTTP",
        "url_path": "/index.html"
    }
}
GET
/v2.0/lb/healthmonitors/​{health_monitor_id}​
Show health monitor details

Shows details for a specified health monitor.

 
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the VIP.

tenant_id plain csapi:uuid

The ID of the tenant who owns the VIP. Only administrative users can specify a tenant ID other than their own.

type plain xsd:string

The type of probe sent by the load balancer to verify the member state, which is PING, TCP, HTTP, or HTTPS.

delay plain xsd:int

The time, in seconds, between sending probes to members.

timeout plain xsd:int

The maximum number of seconds for a monitor to wait for a connection to be established before it times out. This value must be less than the delay value.

max_retries plain xsd:int

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) plain xsd:string

The HTTP method that the monitor uses for requests.

url_path (Optional) plain xsd:string

The HTTP path of the request sent by the monitor to test the health of a member. Must be a string beginning with a forward slash (/).

expected_codes (Optional) plain xsd:string

Expected HTTP codes for a passing HTTP(S) monitor.

admin_state_up (Optional) plain xsd:boolean

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

status plain xsd:string

The status of the health monitor. Indicates whether the health monitor is operational.

{
    "healthmonitor": {
        "admin_state_up": true,
        "delay": 1,
        "expected_codes": "200,201,202",
        "http_method": "GET",
        "id": "0a9ac99d-0a09-4b18-8499-a0796850279a",
        "max_retries": 5,
        "pools": [
            {
                "id": "74aa2010-a59f-4d35-a436-60a6da882819"
            }
        ],
        "tenant_id": "6f3584d5754048a18e30685362b88411",
        "timeout": 1,
        "type": "HTTP",
        "url_path": "/index.html"
    }
}

This operation does not accept a request body.

PUT
/v2.0/lb/healthmonitors/​{health_monitor_id}​
Update health monitor

Updates a specified load balancer health monitor.

 
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Request parameters
Parameter Style Type Description
delay plain xsd:int

The time, in seconds, between sending probes to members.

url_path plain xsd: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 (/).

Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the VIP.

tenant_id plain csapi:uuid

The ID of the tenant who owns the VIP. Only administrative users can specify a tenant ID other than their own.

type plain xsd:string

The type of probe sent by the load balancer to verify the member state, which is PING, TCP, HTTP, or HTTPS.

delay plain xsd:int

The time, in seconds, between sending probes to members.

timeout plain xsd:int

The maximum number of seconds for a monitor to wait for a connection to be established before it times out. This value must be less than the delay value.

max_retries plain xsd:int

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) plain xsd:string

The HTTP method that the monitor uses for requests.

url_path (Optional) plain xsd:string

The HTTP path of the request sent by the monitor to test the health of a member. Must be a string beginning with a forward slash (/).

expected_codes (Optional) plain xsd:string

Expected HTTP codes for a passing HTTP(S) monitor.

admin_state_up (Optional) plain xsd:boolean

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

status plain xsd:string

The status of the health monitor. Indicates whether the health monitor is operational.

{
   "health_monitor":{
      "delay":"3"
   }
}
{
    "health_monitor": {
        "admin_state_up": true,
        "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
        "delay": 5,
        "max_retries": 5,
        "http_method": "GET",
        "timeout": 1,
        "pools": [
            {
                "status": "PENDING_CREATE",
                "status_description": null,
                "pool_id": "6e55751f-6ad4-4e53-b8d4-02e442cd21df"
            }
        ],
        "type": "PING",
        "id": "b05e44b5-81f9-4551-b474-711a722698f7"
    }
}
DELETE
/v2.0/lb/healthmonitors/​{health_monitor_id}​
Delete health monitor

Deletes a specified load balancer health monitor.

 
Normal response codes
204
Error response codes
badRequest (400), unauthorized (401), overLimit (413), Internal-server-error (500), serviceUnavailable (503)

This operation does not return a response body.

GET
/v2.0/lb/pools
List pools

Lists pools.

 
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Response parameters
Parameter Style Type Description
status plain xsd:string

The status of the pool. Indicates whether the pool is operational.

lb_method plain xsd:string

The load-balancer algorithm, which is round-robin, least-connections, 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 plain xsd:string

The protocol of the pool, which is TCP, HTTP, or HTTPS.

description plain xsd:string

Description for the pool.

health_monitors (Optional) plain xsd:list

List of health monitors that are associated with the pool.

subnet_id plain csapi:uuid

All members of this pool are on this subnet.

tenant_id plain csapi:uuid

The ID of the tenant who owns the pool. Only administrative users can specify a tenant ID other than their own.

admin_state_up plain xsd:boolean

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

name plain xsd:string

Pool name. Does not have to be unique.

session_persistence (Optional) plain xsd:dict

The session persistence algorithm, if any, to use. This algorithm is a dictionary with the type and cookie_name keys.

members plain xsd:list

List of members that belong to the pool.

id plain csapi:uuid

The unique ID for the pool.

vip_id plain csapi:uuid

The ID of VIP.

health_monitors_status plain xsd:string

Information about the health monitors that are associated with the pool.

provider plain xsd:string

The load-balancer provider.

{
   "pools":[
      {
         "status":"ACTIVE",
         "lb_method":"ROUND_ROBIN",
         "protocol":"HTTP",
         "description":"",
         "health_monitors":[
            "466c8345-28d8-4f84-a246-e04380b0461d",
            "5d4b5228-33b0-4e60-b225-9b727c1a20e7"
         ],
         "subnet_id":"8032909d-47a1-4715-90af-5153ffe39861",
         "tenant_id":"83657cfcdfe44cd5920adaf26c48ceea",
         "admin_state_up":true,
         "name":"app_pool",
         "members":[
            "701b531b-111a-4f21-ad85-4795b7b12af6",
            "beb53b4d-230b-4abd-8118-575b8fa006ef"
         ],
         "id":"72741b06-df4d-4715-b142-276b6bce75ab",
         "vip_id":"4ec89087-d057-4e2c-911f-60a3b47ee304"
      }
   ]
}

This operation does not accept a request body.

POST
/v2.0/lb/pools
Create a load balancer pool

Creates a load balancer pool.

 
Normal response codes
201
Error response codes
badRequest (400), unauthorized (401), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Request parameters
Parameter Style Type Description
tenant_id plain csapi:uuid

The ID of the tenant who owns the pool. Only administrative users can specify a tenant ID other than their own.

name plain xsd:string

Pool name. Does not have to be unique.

protocol plain xsd:string

The protocol of the pool, which is TCP, HTTP, or HTTPS.

subnet_id plain csapi:uuid

The ID of the subnet on which to allocate the VIP address.

lb_method plain xsd:string

The load-balancer algorithm, which is round-robin, least-connections, 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.

Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the VIP.

tenant_id plain csapi:uuid

The ID of the tenant who owns the VIP. Only administrative users can specify a tenant ID other than their own.

name plain xsd:string

Human-readable name for the VIP. Does not have to be unique.

description plain xsd:string

Human-readable description for the VIP.

subnet_id plain csapi:uuid

The ID of the subnet on which to allocate the VIP address.

port_id plain csapi:uuid

The ID of the VIP port.

address plain xsd:ip

The IP address of the VIP.

protocol plain xsd:string

The protocol of the VIP address. A valid value is TCP, HTTP, or HTTPS.

protocol_port plain xsd:int

The port on which to listen to client traffic that is associated with the VIP address. A valid value is from 0 to 65535.

pool_id plain csapi:uuid

The ID of the pool with which the VIP is associated.

session_persistence plain xsd:dict

Session persistence parameters for the VIP. Omit the session_persistence parameter to prevent session persistence. When no session persistence is used, the session_persistence parameter does not appear in the API response. To clear session persistence for the VIP, set the session_persistence parameter to null in a VIP update request.

connection_limit plain xsd:int

The maximum number of connections allowed for the VIP. Default is -1, meaning no limit.

admin_state_up plain xsd:boolean

The administrative state of the VIP. A valid value is true (UP) or false (DOWN).

status plain xsd:string

The status of the VIP. Indicates whether the VIP is operational.

{
    "pool": {
        "admin_state_up": true,
        "description": "simple pool",
        "lb_algorithm": "ROUND_ROBIN",
        "listener_id": "39de4d56-d663-46e5-85a1-5b9d5fa17829",
        "name": "pool1",
        "protocol": "HTTP",
        "session_persistence": {
            "cookie_name": "my_cookie",
            "type": "APP_COOKIE"
        }
    }
}
{
    "pool": {
        "admin_state_up": true,
        "description": "simple pool",
        "healthmonitor_id": null,
        "id": "12ff63af-4127-4074-a251-bcb2ecc53ebe",
        "lb_algorithm": "ROUND_ROBIN",
        "listeners": [
            {
                "id": "39de4d56-d663-46e5-85a1-5b9d5fa17829"
            }
        ],
        "members": [],
        "name": "pool1",
        "protocol": "HTTP",
        "session_persistence": {
            "cookie_name": "my_cookie",
            "type": "APP_COOKIE"
        },
        "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c"
    }
}
GET
/v2.0/lb/pools/​{pool_id}​
Show pool details

Shows details for a specified pool.

 
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Request parameters
Parameter Style Type Description
pool_id URI csapi:UUID The UUID for the pool.
Response parameters
Parameter Style Type Description
status plain xsd:string

The status of the pool. Indicates whether the pool is operational.

lb_method plain xsd:string

The load-balancer algorithm, which is round-robin, least-connections, 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 plain xsd:string

The protocol of the pool, which is TCP, HTTP, or HTTPS.

description plain xsd:string

Description for the pool.

health_monitors (Optional) plain xsd:list

List of health monitors that are associated with the pool.

subnet_id plain csapi:uuid

All members of this pool are on this subnet.

tenant_id plain csapi:uuid

The ID of the tenant who owns the pool. Only administrative users can specify a tenant ID other than their own.

admin_state_up plain xsd:boolean

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

name plain xsd:string

Pool name. Does not have to be unique.

session_persistence (Optional) plain xsd:dict

The session persistence algorithm, if any, to use. This algorithm is a dictionary with the type and cookie_name keys.

members plain xsd:list

List of members that belong to the pool.

id plain csapi:uuid

The unique ID for the pool.

vip_id plain csapi:uuid

The ID of VIP.

health_monitors_status plain xsd:string

Information about the health monitors that are associated with the pool.

provider plain xsd:string

The load-balancer provider.

{
    "pool": {
        "admin_state_up": true,
        "description": "simple pool",
        "healthmonitor_id": null,
        "id": "4c0a0a5f-cf8f-44b7-b912-957daa8ce5e5",
        "lb_algorithm": "ROUND_ROBIN",
        "listeners": [
            {
                "id": "35cb8516-1173-4035-8dae-0dae3453f37f"
            }
        ],
        "members": [],
        "name": "pool1",
        "protocol": "HTTP",
        "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c"
    }
}

This operation does not accept a request body.

PUT
/v2.0/lb/pools/​{pool_id}​
Update pool

Updates a specified load balancer pool.

 
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Request parameters
Parameter Style Type Description
pool_id URI csapi:UUID The UUID for the pool.
name plain xsd:string

Pool name. Does not have to be unique.

lb_method plain xsd:string

The load-balancer algorithm, which is round-robin, least-connections, 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.

Response parameters
Parameter Style Type Description
status plain xsd:string

The status of the pool. Indicates whether the pool is operational.

lb_method plain xsd:string

The load-balancer algorithm, which is round-robin, least-connections, 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 plain xsd:string

The protocol of the pool, which is TCP, HTTP, or HTTPS.

description plain xsd:string

Description for the pool.

health_monitors (Optional) plain xsd:list

List of health monitors that are associated with the pool.

subnet_id plain csapi:uuid

All members of this pool are on this subnet.

tenant_id plain csapi:uuid

The ID of the tenant who owns the pool. Only administrative users can specify a tenant ID other than their own.

admin_state_up plain xsd:boolean

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

name plain xsd:string

Pool name. Does not have to be unique.

session_persistence (Optional) plain xsd:dict

The session persistence algorithm, if any, to use. This algorithm is a dictionary with the type and cookie_name keys.

members plain xsd:list

List of members that belong to the pool.

id plain csapi:uuid

The unique ID for the pool.

vip_id plain csapi:uuid

The ID of VIP.

health_monitors_status plain xsd:string

Information about the health monitors that are associated with the pool.

provider plain xsd:string

The load-balancer provider.

{
   "pool":{
      "name":"SuperPool"
   }
}
{
   "pool":{
      "status":"PENDING_UPDATE",
      "lb_method":"ROUND_ROBIN",
      "protocol":"TCP",
      "description":"",
      "health_monitors":[

      ],
      "subnet_id":"8032909d-47a1-4715-90af-5153ffe39861",
      "tenant_id":"83657cfcdfe44cd5920adaf26c48ceea",
      "admin_state_up":true,
      "name":"SuperPool",
      "members":[

      ],
      "id":"61b1f87a-7a21-4ad3-9dda-7f81d249944f",
      "vip_id":null
   }
}
DELETE
/v2.0/lb/pools/​{pool_id}​
Delete pool

Deletes a specified load balancer pool.

 
Normal response codes
204
Error response codes
badRequest (400), unauthorized (401), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Request parameters
Parameter Style Type Description
pool_id URI csapi:UUID The UUID for the pool.

This operation does not accept a request body and does not return a response body.

POST
/v2.0/lb/pools/​{pool_id}​/health_monitors
Associate health monitor with pool

Associates a health monitor with a specified pool.

 
Normal response codes
201
Error response codes
badRequest (400), unauthorized (401), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Request parameters
Parameter Style Type Description
pool_id URI csapi:UUID The UUID for the pool.
tenant_id plain csapi:uuid

The ID of the tenant who owns the VIP. Only administrative users can specify a tenant ID other than their own.

type plain xsd:string

The type of probe that is sent by the load balancer to verify the member state. A valid value is PING, TCP, HTTP, or HTTPS.

delay plain xsd:int

The time, in seconds, between sending probes to members.

timeout plain xsd:int

Time in seconds to timeout each probe.

max_retries plain xsd:int

Maximum consecutive health probe tries.

url_path (Optional) plain xsd:string

Path portion of URI that will be probed if type is HTTP(S).

expected_codes (Optional) plain xsd:string

Expected HTTP codes for a passing HTTP(S) monitor.

Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the VIP.

tenant_id plain csapi:uuid

The ID of the tenant who owns the VIP. Only administrative users can specify a tenant ID other than their own.

type plain xsd:string

The type of probe sent by the load balancer to verify the member state, which is PING, TCP, HTTP, or HTTPS.

delay plain xsd:int

The time, in seconds, between sending probes to members.

timeout plain xsd:int

The maximum number of seconds for a monitor to wait for a connection to be established before it times out. This value must be less than the delay value.

max_retries plain xsd:int

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) plain xsd:string

The HTTP method that the monitor uses for requests.

url_path (Optional) plain xsd:string

The HTTP path of the request sent by the monitor to test the health of a member. Must be a string beginning with a forward slash (/).

expected_codes (Optional) plain xsd:string

Expected HTTP codes for a passing HTTP(S) monitor.

admin_state_up (Optional) plain xsd:boolean

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

status plain xsd:string

The status of the health monitor. Indicates whether the health monitor is operational.

{
   "health_monitor":{
      "id":"b624decf-d5d3-4c66-9a3d-f047e7786181"
   }
}
{
   "health_monitor":{

   }
}
DELETE
/v2.0/lb/pools/​{pool_id}​/health_monitors/​{health_monitor_id}​
Disassociate health monitor from pool

Disassociates a specified health monitor from a pool.

 
Normal response codes
204
Error response codes
badRequest (400), unauthorized (401), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Request parameters
Parameter Style Type Description
pool_id URI csapi:UUID The UUID for the pool.
health_monitor_id URI csapi:UUID The UUID for the health monitor.

This operation does not accept a request body and does not return a response body.

GET
/v2.0/lb/members
List members

Lists members.

 
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the member.

tenant_id plain csapi:uuid

The ID of the tenant who owns the member. Only administrative users can specify a tenant ID other than their own.

subnet_id plain csapi:uuid

Subnet in which to access this member.

address plain xsd:ip

The IP address of the member.

protocol_port plain xsd:int

The port where the application is hosted.

weight plain xsd:int

Weight of member.

admin_state_up plain xsd:boolean

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

status plain xsd:string

The status of the member. Indicates whether the member is operational.

{
   "members":[
      {
         "status":"ACTIVE",
         "weight":1,
         "admin_state_up":true,
         "tenant_id":"83657cfcdfe44cd5920adaf26c48ceea",
         "pool_id":"72741b06-df4d-4715-b142-276b6bce75ab",
         "address":"10.0.0.4",
         "protocol_port":80,
         "id":"701b531b-111a-4f21-ad85-4795b7b12af6"
      },
      {
         "status":"ACTIVE",
         "weight":1,
         "admin_state_up":true,
         "tenant_id":"83657cfcdfe44cd5920adaf26c48ceea",
         "pool_id":"72741b06-df4d-4715-b142-276b6bce75ab",
         "address":"10.0.0.3",
         "protocol_port":80,
         "id":"beb53b4d-230b-4abd-8118-575b8fa006ef"
      }
   ]
}

This operation does not accept a request body.

POST
/v2.0/lb/members
Create a load balancer member

Creates a load balancer member.

 
Normal response codes
201
Error response codes
badRequest (400), unauthorized (401), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Request parameters
Parameter Style Type Description
tenant_id plain csapi:uuid

The ID of the tenant who owns the member. Only administrative users can specify a tenant ID other than their own.

address plain xsd:ip

The IP address of the member.

protocol_port plain xsd:int

The port where the application is hosted.

subnet_id plain xsd:int

Subnet in which to access this member.

Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the member.

tenant_id plain csapi:uuid

The ID of the tenant who owns the member. Only administrative users can specify a tenant ID other than their own.

subnet_id plain csapi:uuid

Subnet in which to access this member.

address plain xsd:ip

The IP address of the member.

protocol_port plain xsd:int

The port where the application is hosted.

weight plain xsd:int

Weight of member.

admin_state_up plain xsd:boolean

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

status plain xsd:string

The status of the member. Indicates whether the member is operational.

{
    "member": {
        "address": "10.0.0.8",
        "admin_state_up": true,
        "protocol_port": "80",
        "subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2",
        "weight": "1"
    }
}
{
    "member": {
        "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
    }
}
GET
/v2.0/lb/members/​{member_id}​
Show member details

Shows details for a specified member.

 
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Request parameters
Parameter Style Type Description
member_id URI csapi:UUID The UUID for the member.
Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the member.

tenant_id plain csapi:uuid

The ID of the tenant who owns the member. Only administrative users can specify a tenant ID other than their own.

subnet_id plain csapi:uuid

Subnet in which to access this member.

address plain xsd:ip

The IP address of the member.

protocol_port plain xsd:int

The port where the application is hosted.

weight plain xsd:int

Weight of member.

admin_state_up plain xsd:boolean

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

status plain xsd:string

The status of the member. Indicates whether the member is operational.

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

This operation does not accept a request body.

PUT
/v2.0/lb/members/​{member_id}​
Update member

Updates a specified load balancer member.

 
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Request parameters
Parameter Style Type Description
member_id URI csapi:UUID The UUID for the member.
admin_state_up plain xsd:boolean

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

Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the member.

tenant_id plain csapi:uuid

The ID of the tenant who owns the member. Only administrative users can specify a tenant ID other than their own.

subnet_id plain csapi:uuid

Subnet in which to access this member.

address plain xsd:ip

The IP address of the member.

protocol_port plain xsd:int

The port where the application is hosted.

weight plain xsd:int

Weight of member.

admin_state_up plain xsd:boolean

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

status plain xsd:string

The status of the member. Indicates whether the member is operational.

{
   "member":{
      "admin_state_up":false
   }
}
{
   "member":{
      "status":"PENDING_UPDATE",
      "protocol_port":8080,
      "weight":1,
      "admin_state_up":false,
      "tenant_id":"4fd44f30292945e481c7b8a0c8908869",
      "pool_id":"7803631d-f181-4500-b3a2-1b68ba2a75fd",
      "address":"10.0.0.5",
      "status_description":null,
      "id":"48a471ea-64f1-4eb6-9be7-dae6bbe40a0f"
   }
}
DELETE
/v2.0/lb/members/​{member_id}​
Delete member

Deletes a specified load balancer member.

 
Normal response codes
204
Error response codes
badRequest (400), unauthorized (401), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Request parameters
Parameter Style Type Description
member_id URI csapi:UUID The UUID for the member.

This operation does not accept a request body and does not return a response body.

Load-Balancer-as-a-Service (LBaaS) 2.0 (EXPERIMENTAL)

The 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 associated with a pool and view status of a resource.

Load balancer statuses
Status Description

ACTIVE

Resource is ready and active.

PENDING_CREATE

Resource is being created.

PENDING_UPDATE

Resource is being updated.

PENDING_DELETE

Resource is pending deletion.

INACTIVE

Resource was created but is not active.

ERROR

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

 

Lists all load balancers that are associated with your tenant account.

This operation does not require a request body.

This operation returns a response body. It returns a (potentially empty) list. Each element in the list is a load balancer that can contain the following attributes:

  • id

  • tenant_id

  • name

  • description

  • vip_subnet_id

  • vip_address

  • admin_state_up

  • listeners

  • provisioning_status

  • operating_status

Normal response codes
200
Error response codes
unauthorized (401), Internal-server-error (500), serviceUnavailable (503)
Response parameters
Parameter Style Type Description
loadbalancers plain xsd:string

A loadbalancers object.

loadbalancer plain xsd:string

A loadbalancer object.

id plain csapi:uuid

The unique ID for the load balancer.

name plain xsd:string

Load balancer name.

description plain xsd:string

Load balancer description.

vip_address plain xsd:ip

The IP address of the VIP.

vip_subnet_id plain csapi:uuid

The ID of the subnet on which to allocate the VIP address.

status plain xsd:string

The status of the load balancer. Indicates whether the load balancer is operational.

admin_state_up plain xsd:boolean

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

tenant_id plain csapi:uuid

The ID of the tenant who owns the VIP. Only administrative users can specify a tenant ID other than their own.

{
    "loadbalancers": [
        {
            "id": "3b98602c-3cfe-4f91-bfa4-c3a11c9e7fe0",
            "name": "Example LB",
            "description": "A very simple example load balancer.",
            "tenant_id": "783b31af-6635-48b2-a807-091d9973e3a9",
            "admin_state_up": true,
            "status": "ACTIVE"
        },
        {
            "id": "c617c538-daa5-4ead-be88-59521d8745a7",
            "name": "Example LB",
            "description": "A very simple example load balancer.",
            "tenant_id": "783b31af-6635-48b2-a807-091d9973e3a9",
            "admin_state_up": true,
            "status": "ACTIVE"
        }
    ]
}

This operation does not accept a request body.

POST
/v2.0/lbaas/loadbalancers
Create load balancer

Creates a load balancer.

 

This operation provisions a new load balancer based on the configuration defined in the request object. After the request is validated and progress has started on the provisioning process, a response object is returned. The object contains a unique identifier and the status of provisioning the load balancer.

The provisioning_status of the load balancer in the response can have one of the following values: ACTIVE, PENDING_CREATE, or ERROR.

If the status is PENDING_CREATE, the caller can view the progress of the provisioning operation by performing a GET on /lbaas/loadbalancers/loadbalancer_id. When the status of the load balancer changes to ACTIVE, the load balancer was successfully provisioned and is operational for traffic handling.

If the request cannot be fulfilled due to insufficient or invalid data, an HTTP 400 (Bad Request) error response is returned with information about the nature of the failure in the response body. Failures in the validation process are non- recoverable and require the caller to correct the cause of the failure and POST 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.

Users with an administrative role can create load balancers on behalf of other tenants by specifying a tenant_id attribute different than their own.

Example: Create a load balancer

  • tenant_id. only required if the caller has an administrative role and wants 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 are authorized by the policy, such as her own networks or shared or provider networks.

Some attributes receive default values if not specified in the request:

  • admin_state_up. The default is true.

  • name. The default is an empty string.

  • description. The default is an empty string.

If the request cannot be fulfilled due to insufficient data or data that is not valid, an HTTP 400 (Bad Request) error response is returned with information about the nature of the failure in the response body. Failures in the validation process are non-recoverable and require the caller to correct the cause of the failure and POST 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.

Users with an administrative role can create load balancers on behalf of other tenants by specifying a tenant_id attribute that is different than their own.

A user can supply a vip_address field if she owns the subnet on which the load balancer's VIP will be created. If a vip_address is not specified in the payload, the LBaaS service allocates one from the load balancer VIP's subnet.

Example: Create a load balancer

Normal response codes
201
Error response codes
unauthorized (401), itemNotFound (404), conflict (409), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Request parameters
Parameter Style Type Description
name (Optional) plain xsd:string

Load balancer name. Does not have to be unique.

description (Optional) plain xsd:string

Load balancer description.

vip_subnet_id (Optional) plain csapi:uuid

The ID of the subnet on which to allocate the VIP address.

tenant_id plain csapi:uuid

The ID of the tenant who owns the load balancer. Only administrative users can specify a tenant ID other than their own.

Response parameters
Parameter Style Type Description
loadbalancer plain xsd:string

A loadbalancer object.

id plain csapi:uuid

The unique ID for the load balancer.

name plain xsd:string

Load balancer name.

description plain xsd:string

Load balancer description.

vip_address plain xsd:ip

The IP address of the VIP.

vip_subnet_id plain csapi:uuid

The ID of the subnet on which to allocate the VIP address.

status plain xsd:string

The status of the load balancer. Indicates whether the load balancer is operational.

admin_state_up plain xsd:boolean

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

tenant_id plain csapi:uuid

The ID of the tenant who owns the VIP. Only administrative users can specify a tenant ID other than their own.

{
    "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
    }
}
{
    "loadbalancer": {
        "admin_state_up": true,
        "description": "simple lb",
        "id": "a36c20d0-18e9-42ce-88fd-82a35977ee8c",
        "listeners": [],
        "name": "loadbalancer1",
        "operating_status": "ONLINE",
        "provisioning_status": "ACTIVE",
        "tenant_id": "b7c1a69e88bf4b21a8148f787aef2081",
        "vip_address": "10.0.0.4",
        "vip_subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2"
    }
}
GET
/v2.0/lbaas/loadbalancers/​{loadbalancer_id}​
Show load balancer details

Shows details for a specified load balancer.

 

This operation returns a load balancer object identified by loadbalancer_id. If the user is not an administrative user and the load balancer object does not belong to her tenant account, she would receive a 403 (Forbidden) error.

This operation does not require a request body.

This operation returns a response body. On success, the returned element is a load balancer that can contain the following attributes:

  • id

  • tenant_id

  • name

  • description

  • vip_subnet_id

  • vip_address

  • admin_state_up

  • listeners

  • provisioning_status

  • operating_status

Example: Show load balancer details

Normal response codes
200
Error response codes
unauthorized (401), forbidden (403), itemNotFound (404), conflict (409), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Response parameters
Parameter Style Type Description
loadbalancer plain xsd:string

A loadbalancer object.

id plain csapi:uuid

The unique ID for the load balancer.

name plain xsd:string

Load balancer name.

description plain xsd:string

Load balancer description.

vip_address plain xsd:ip

The IP address of the VIP.

vip_subnet_id plain csapi:uuid

The ID of the subnet on which to allocate the VIP address.

status plain xsd:string

The status of the load balancer. Indicates whether the load balancer is operational.

admin_state_up plain xsd:boolean

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

tenant_id plain csapi:uuid

The ID of the tenant who owns the VIP. Only administrative users can specify a tenant ID other than their own.

{
   "loadbalancer":{
      "id":"8992a43f-83af-4b49-9afd-c2bfbd82d7d7",
      "name":"Example LB",
      "description":"A very simple example load balancer.",
      "vip_address":"1.2.3.4",
      "vip_subnet_id":"SUBNET_ID",
      "tenant_id":"7725fe12-1c14-4f45-ba8e-44bf01763578",
      "admin_state_up":true,
      "status":"ACTIVE"
   }
}

This operation does not accept a request body.

PUT
/v2.0/lbaas/loadbalancers/​{loadbalancer_id}​
Update load balancer

Updates a specified load balancer.

 

This operation updates the attributes of the specified load balancer. Upon successful validation of the request, the service returns a 202 (Accepted) response code. A caller should check that the load balancer provisioning_status has changed to ACTIVE to confirm that the update has taken effect. If the load balancer provisioning_status is PENDING_UPDATE, the caller can poll the load balancer object by using a GET operation to wait for the changes to be applied.

The update operation allows the caller to change one or more of the following load balancer attributes:

  • name

  • description

  • admin_state_up

This operation returns the updated load balancer object. The provisioning_status of the load balancer in the response can take one of the following values: ACTIVE, PENDING_UPDATE, or ERROR.

Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Request parameters
Parameter Style Type Description
loadbalancer plain xsd:string

A loadbalancer object.

name (Optional) plain xsd:string

Load balancer name. Does not have to be unique.

description (Optional) plain xsd:string

Load balancer description.

Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the load balancer.

name plain xsd:string

Load balancer name.

description plain xsd:string

Load balancer description.

vip_address plain xsd:ip

The IP address of the VIP.

vip_subnet_id plain csapi:uuid

The ID of the subnet on which to allocate the VIP address.

status plain xsd:string

The status of the load balancer. Indicates whether the load balancer is operational.

admin_state_up plain xsd:boolean

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

tenant_id plain csapi:uuid

The ID of the tenant who owns the VIP. Only administrative users can specify a tenant ID other than their own.

{
    "loadbalancer": {
        "admin_state_up": false,
        "description": "simple lb2",
        "name": "loadbalancer2"
    }
}
{
    "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 specified load balancer.

 

This operation removes the specified load balancer and its associated configuration from the tenant account. Any and all configuration data is immediately purged and cannot be recovered.

This operation does not require a request body.

This operation does not return a response body.

Example: Delete a load balancer

Normal response codes
204
Error response codes
badRequest (400), unauthorized (401), overLimit (413), Internal-server-error (500), serviceUnavailable (503)

This operation does not accept a request body and does not return a response body.

GET
/v2.0/lbaas/listeners
List listeners

Lists listeners.

 

This operation lists all listeners associated with your tenant account.

This operation does not require a request body.

This operation returns a response body. It returns a (potentially empty) list. Each list element is a listener that can contain the following attributes:

  • id

  • tenant_id

  • name

  • description

  • protocol

  • protocol_port

  • connection_limit

  • default_pool_id

  • admin_state_up

  • loadbalancers

  • default_tls_container_ref

  • sni_container_refs

Example: List listeners

Normal response codes
200
Error response codes
unauthorized (401), Internal-server-error (500), serviceUnavailable (503)
{
    "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"
            ]
        }
    ]
}

This operation does not accept a request body.

POST
/v2.0/lbaas/listeners
Create listener

Creates a listener.

 

This operation provisions a new listener based on the configuration defined in the request object. After the request is validated and progress has started on the provisioning process, a response object is returned. The object contains a unique identifier.

The caller of this operation must specify these listener attributes, at a minimum:

  • tenant_id. Required only if the caller has an administrative role and wants to create a listener for another tenant.

  • loadbalancer_id. The load balancer on which this listener is provisioned. A tenant can only create listeners on load balancers authorized by policy. For example, her own load balancers.

  • description. The load balancer description.

  • protocol. The protocol for which the front end listens. Must be TCP, HTTP, or HTTPS.

  • 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 will be the default.

  • sni_container_refs. A list of references to containers that hold TLS secrets that are used for Server Name Indication (SNI).

Some attributes receive default values if not specified in the request:

  • admin_state_up. The default is true.

  • name. The default is an empty string.

  • description. The default is an empty string.

  • connection_limit. The default is -1, which indicates an infinite limit.

If the request cannot be fulfilled due to insufficient or invalid data, an HTTP 400 (Bad Request) error response is returned with information regarding the nature of the failure in the response body. Failures in the validation process are non-recoverable and require the caller to correct the cause of the failure and POST 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.

Users with an administrative role can create listeners on behalf of other tenants by specifying a tenant_id attribute different than their own.

A listener cannot be updated if the load balancer that it is attempting to be attached to does not have a provisioning_status of ACTIVE.

Example: Create a listener

Normal response codes
201
Error response codes
unauthorized (401), itemNotFound (404), conflict (409), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Request parameters
Parameter Style Type Description
listener (Optional) plain xsd:string

A listener object.

default_pool_id (Optional) plain csapi:uuid

The ID of default pool. Must have compatible protocol with listener.

name plain xsd:string

The listener name.

description (Optional) plain xsd:string

Detailed description of the listener.

tenant_id plain csapi:uuid

The ID of the tenant who owns the listener. Only administrative users can specify a tenant ID other than their own.

connection_limit (Optional) plain xsd:int

The maximum number of connections permitted for this load balancer. Default is infinite.

protocol plain xsd:string

The protocol to load balance. A valid values is HTTP, HTTPS, TCP, or UDP.

protocol_port plain xsd:int

The TCP or UDP port on which to listen.

admin_state_up (Optional) plain xsd:boolean

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

Set this attribute to false to create the listener in an administratively down state.

loadbalancer_id (Optional) plain csapi:uuid

The ID of the load balancer.

default_tls_container_ref (Optional) plain xsd:string

A reference to a container of TLS secrets.

sni_container_refs (Optional) plain xsd:list

A list of references to TLS secrets.

{
    "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"
        ]
    }
}
{
    "listener": {
        "admin_state_up": true,
        "connection_limit": 100,
        "default_pool_id": null,
        "description": "listener one",
        "id": "39de4d56-d663-46e5-85a1-5b9d5fa17829",
        "loadbalancers": [
            {
                "id": "a36c20d0-18e9-42ce-88fd-82a35977ee8c"
            }
        ],
        "name": "listener1",
        "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"
        ]
    }
}
GET
/v2.0/lbaas/listeners/​{listener_id}​
Show listener details

Shows details for a specified listener.

 

This operation returns a listener object identified by listener_id. If the user is not an administrative user, and the listener object does not belong to her tenant account, she receives a 403 (Forbidden) error.

This operation does not require a request body.

This operation returns a response body. On success, the returned element is a listener that can contain the following attributes:

  • id

  • tenant_id

  • name

  • description

  • protocol

  • protocol_port

  • connection_limit

  • default_pool_id

  • admin_state_up

  • loadbalancers

  • default_tls_container_ref

  • sni_container_refs

Example: Show listener details

Normal response codes
200
Error response codes
unauthorized (401), forbidden (403), itemNotFound (404), conflict (409), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
{
    "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"
        ]
    }
}

This operation does not accept a request body.

PUT
/v2.0/lbaas/listeners/​{listener_id}​
Update listener

Updates a specified listener.

 

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

The update operation allows the caller to change one or more of the following listener attributes:

  • name

  • description

  • admin_state_up

  • connection_limit

  • default_tls_container_ref

  • sni_container_refs

Example: Update a listener

Note: You cannot update these listener attributes: listener_id, tenant_id, loadbalancer_id, loadbalancers, default_pool_id, protocol, and protocol_port. Attempting to update an immutable attribute results in a 422 (Immutable) fault.

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

Normal response codes
200
Error response codes
Internal-server-error (500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
Request parameters
Parameter Style Type Description
listener (Optional) plain xsd:string

A listener object.

default_pool_id (Optional) plain csapi:uuid

The ID of default pool. Must have compatible protocol with listener.

name plain xsd:string

The listener name.

description (Optional) plain xsd:string

Detailed description of the listener.

tenant_id plain csapi:uuid

The ID of the tenant who owns the listener. Only administrative users can specify a tenant ID other than their own.

connection_limit (Optional) plain xsd:int

The maximum number of connections permitted for this load balancer. Default is infinite.

protocol plain xsd:string

The protocol to load balance. A valid values is HTTP, HTTPS, TCP, or UDP.

protocol_port plain xsd:int

The TCP or UDP port on which to listen.

admin_state_up (Optional) plain xsd:boolean

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

Set this attribute to false to create the listener in an administratively down state.

loadbalancer_id (Optional) plain csapi:uuid

The ID of the load balancer.

default_tls_container_ref (Optional) plain xsd:string

A reference to a container of TLS secrets.

sni_container_refs (Optional) plain xsd:list

A list of references to TLS secrets.

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

 

This operation removes a specified listener and its associated configuration from the tenant account. Any and all configuration data is immediately purged and is not recoverable.

This operation does not require a request body.

This operation does not return a response body.

You cannot delete a listener if the load balancer to which it is attached does not have a provisioning_status of ACTIVE.

Example: Delete a listener

Normal response codes
204
Error response codes
badRequest (400), unauthorized (401), conflict (409), overLimit (413), Internal-server-error (500), serviceUnavailable (503)

This operation does not accept a request body and does not return a response body.

GET
/v2.0/lbaas/pools
List pools

Lists pools.

 

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

This operation does not require a request body.

This operation returns a response body. It returns a (potentially empty) list. Each element in the list is a pool that can contain the following attributes:

  • id

  • tenant_id

  • name

  • description

  • protocol

  • lb_method

  • session_persistence

  • admin_state_up

  • listeners

  • members

  • healthmonitor_id

Example: List pools

Normal response codes
200
Error response codes
unauthorized (401), Internal-server-error (500), serviceUnavailable (503)
Response parameters
Parameter Style Type Description
status plain xsd:string

The status of the pool. Indicates whether the pool is operational.

lb_method plain xsd:string

The load-balancer algorithm, which is round-robin, least-connections, 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 plain xsd:string

The protocol of the pool, which is TCP, HTTP, or HTTPS.

description plain xsd:string

Description for the pool.

health_monitors (Optional) plain xsd:list

List of health monitors that are associated with the pool.

subnet_id plain csapi:uuid

All members of this pool are on this subnet.

tenant_id plain csapi:uuid

The ID of the tenant who owns the pool. Only administrative users can specify a tenant ID other than their own.

admin_state_up plain xsd:boolean

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

name plain xsd:string

Pool name. Does not have to be unique.

session_persistence (Optional) plain xsd:dict

The session persistence algorithm, if any, to use. This algorithm is a dictionary with the type and cookie_name keys.

members plain xsd:list

List of members that belong to the pool.

id plain csapi:uuid

The unique ID for the pool.

vip_id plain csapi:uuid

The ID of VIP.

health_monitors_status plain xsd:string

Information about the health monitors that are associated with the pool.

provider plain xsd:string

The load-balancer provider.

{
    "pools": [
        {
            "admin_state_up": true,
            "description": "simple pool",
            "healthmonitor_id": null,
            "id": "4c0a0a5f-cf8f-44b7-b912-957daa8ce5e5",
            "lb_algorithm": "ROUND_ROBIN",
            "listeners": [
                {
                    "id": "35cb8516-1173-4035-8dae-0dae3453f37f"
                }
            ],
            "members": [],
            "name": "pool1",
            "protocol": "HTTP",
            "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c"
        }
    ]
}

This operation does not accept a request body.

POST
/v2.0/lbaas/pools
Create pool

Creates a pool.

 

This operation provisions a new pool based on the configuration defined in the request object. After the request is validated and progress has started on the provisioning process, a response object is returned. The object contains a unique identifier.

The caller of this operation must specify these pool attributes, at a minimum:

  • tenant_id. Only required if the caller has an administrative role and wants to create a pool for another tenant.

  • protocol. The protocol this pool and its members listen for. Must be one of TCP, HTTP, or HTTPS

  • lb_method. The load-balancer algorithm, which is round-robin, least-connections, 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_port. The port on which the front end listens. Must be an integer in the range from 1 to 65535.

  • listener_id. The listener in which this pool becomes the default pool. There can only be on default pool for a listener.

Some attributes receive default values if not specified in the request:

  • admin_state_up. The default is true.

  • name. The default is an empty string.

  • description. The default is an empty string.

  • session_persistence. The default is an empty dictionary.

If the request cannot be fulfilled due to insufficient or invalid data, an HTTP 400 (Bad Request) error response is returned with information about the nature of the failure in the response body. Failures in the validation process are non-recoverable and require the caller to correct the cause of the failure and POST the request again.

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

Users with an administrative role can create pools on behalf of other tenants by specifying a tenant_id attribute that is different than their own.

You cannot update a pool if the load balancer to which it is attempting to be attached does not have a provisioning_status of ACTIVE.

Example: Create a pool

Normal response codes
201
Error response codes
unauthorized (401), itemNotFound (404), conflict (409), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Request parameters
Parameter Style Type Description
tenant_id plain csapi:uuid

The ID of the tenant who owns the pool. Only administrative users can specify a tenant ID other than their own.

name plain xsd:string

Pool name. Does not have to be unique.

protocol plain xsd:string

The protocol of the pool, which is TCP, HTTP, or HTTPS.

subnet_id plain csapi:uuid

The ID of the subnet on which to allocate the VIP address.

lb_method plain xsd:string

The load-balancer algorithm, which is round-robin, least-connections, 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.

Response parameters
Parameter Style Type Description
status plain xsd:string

The status of the pool. Indicates whether the pool is operational.

protocol plain xsd:string

The protocol of the pool, which is TCP, HTTP, or HTTPS.

description (Optional) plain xsd:string

Description for the pool.

tenant_id plain csapi:uuid

The ID of the tenant who owns the pool. Only administrative users can specify a tenant ID other than their own.

admin_state_up (Optional) plain xsd:boolean

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

name plain xsd:string

Pool name. Does not have to be unique.

members plain xsd:list

List of members that belong to the pool.

lb_method plain xsd:list

The load-balancer algorithm, which is round-robin, least-connections, 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.

healthmonitor_id (Optional) plain xsd:string

The ID of the health monitor.

session_persistence (Optional) plain xsd:string

The session persistence algorithm. This algorithm is a dictionary with type and cookie_name keys.

id plain csapi:uuid

The unique ID for the pool.

{
    "pool": {
        "admin_state_up": true,
        "description": "simple pool",
        "lb_algorithm": "ROUND_ROBIN",
        "listener_id": "39de4d56-d663-46e5-85a1-5b9d5fa17829",
        "name": "pool1",
        "protocol": "HTTP",
        "session_persistence": {
            "cookie_name": "my_cookie",
            "type": "APP_COOKIE"
        }
    }
}
{
    "pool": {
        "admin_state_up": true,
        "description": "simple pool",
        "healthmonitor_id": null,
        "id": "12ff63af-4127-4074-a251-bcb2ecc53ebe",
        "lb_algorithm": "ROUND_ROBIN",
        "listeners": [
            {
                "id": "39de4d56-d663-46e5-85a1-5b9d5fa17829"
            }
        ],
        "members": [],
        "name": "pool1",
        "protocol": "HTTP",
        "session_persistence": {
            "cookie_name": "my_cookie",
            "type": "APP_COOKIE"
        },
        "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c"
    }
}
GET
/v2.0/lbaas/pools/​{pool_id}​
Show pool details

Shows details for a specified pool.

 

This operation returns a pool object identified by pool_id. If the user is not an administrative user and the pool object does not belong to her tenant account, she receives a 403 (Forbidden) error.

This operation does not require a request body.

This operation returns a response body. On success, the returned element is a pool that can contain the following attributes:

  • id

  • tenant_id

  • name

  • description

  • protocol

  • lb_method

  • session_persistence

  • admin_state_up

  • listeners

  • members

  • healthmonitor_id

Example: Show pool details

Normal response codes
200
Error response codes
unauthorized (401), forbidden (403), itemNotFound (404), conflict (409), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Response parameters
Parameter Style Type Description
status plain xsd:string

The status of the pool. Indicates whether the pool is operational.

lb_method plain xsd:string

The load-balancer algorithm, which is round-robin, least-connections, 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 plain xsd:string

The protocol of the pool, which is TCP, HTTP, or HTTPS.

description plain xsd:string

Description for the pool.

health_monitors (Optional) plain xsd:list

List of health monitors that are associated with the pool.

subnet_id plain csapi:uuid

All members of this pool are on this subnet.

tenant_id plain csapi:uuid

The ID of the tenant who owns the pool. Only administrative users can specify a tenant ID other than their own.

admin_state_up plain xsd:boolean

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

name plain xsd:string

Pool name. Does not have to be unique.

session_persistence (Optional) plain xsd:dict

The session persistence algorithm, if any, to use. This algorithm is a dictionary with the type and cookie_name keys.

members plain xsd:list

List of members that belong to the pool.

id plain csapi:uuid

The unique ID for the pool.

vip_id plain csapi:uuid

The ID of VIP.

health_monitors_status plain xsd:string

Information about the health monitors that are associated with the pool.

provider plain xsd:string

The load-balancer provider.

{
    "pool": {
        "admin_state_up": true,
        "description": "simple pool",
        "healthmonitor_id": null,
        "id": "4c0a0a5f-cf8f-44b7-b912-957daa8ce5e5",
        "lb_algorithm": "ROUND_ROBIN",
        "listeners": [
            {
                "id": "35cb8516-1173-4035-8dae-0dae3453f37f"
            }
        ],
        "members": [],
        "name": "pool1",
        "protocol": "HTTP",
        "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c"
    }
}

This operation does not accept a request body.

PUT
/v2.0/lbaas/pools/​{pool_id}​
Update pool

Updates a specified pool.

 

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

The update operation allows the caller to change one or more of the following pool attributes:

  • name

  • description

  • admin_state_up

  • lb_method

  • session_persistence

Note: You cannot update these attributes: pool ID, tenant_id, listener_id, listeners, healthmonitor_id, protocol, and members are immutable attributes. If you try to update any of these attributes, a 422 (Immutable) fault is returned.

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

Example: Update a pool

Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Request parameters
Parameter Style Type Description
name plain xsd:string

Pool name. Does not have to be unique.

lb_method plain xsd:string

The load-balancer algorithm, which is round-robin, least-connections, 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.

Response parameters
Parameter Style Type Description
status plain xsd:string

The status of the pool. Indicates whether the pool is operational.

lb_method plain xsd:string

The load-balancer algorithm, which is round-robin, least-connections, 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 plain xsd:string

The protocol of the pool, which is TCP, HTTP, or HTTPS.

description plain xsd:string

Description for the pool.

health_monitors (Optional) plain xsd:list

List of health monitors that are associated with the pool.

subnet_id plain csapi:uuid

All members of this pool are on this subnet.

tenant_id plain csapi:uuid

The ID of the tenant who owns the pool. Only administrative users can specify a tenant ID other than their own.

admin_state_up plain xsd:boolean

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

name plain xsd:string

Pool name. Does not have to be unique.

session_persistence (Optional) plain xsd:dict

The session persistence algorithm, if any, to use. This algorithm is a dictionary with the type and cookie_name keys.

members plain xsd:list

List of members that belong to the pool.

id plain csapi:uuid

The unique ID for the pool.

vip_id plain csapi:uuid

The ID of VIP.

health_monitors_status plain xsd:string

Information about the health monitors that are associated with the pool.

provider plain xsd:string

The load-balancer provider.

{
    "pool": {
        "admin_state_up": false,
        "description": "pool two",
        "lb_algorithm": "LEAST_CONNECTIONS",
        "name": "pool2",
        "session_persistence": {
            "type": "HTTP_COOKIE"
        }
    }
}
{
    "pool": {
        "admin_state_up": false,
        "description": "pool two",
        "healthmonitor_id": null,
        "id": "12ff63af-4127-4074-a251-bcb2ecc53ebe",
        "lb_algorithm": "LEAST_CONNECTIONS",
        "listeners": [
            {
                "id": "39de4d56-d663-46e5-85a1-5b9d5fa17829"
            }
        ],
        "members": [],
        "name": "pool2",
        "protocol": "HTTP",
        "session_persistence": {
            "cookie_name": null,
            "type": "HTTP_COOKIE"
        },
        "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c"
    }
}
DELETE
/v2.0/lbaas/pools/​{pool_id}​
Remove pool

Removes a specified pool.

 

This operation removes a specified pool and its associated configuration from the tenant account. Any and all configuration data is immediately purged and is not recoverable.

This operation does not require a request body.

This operation does not return a response body.

You cannot delete a pool if the load balancer to which it is attached does not have a provisioning_status of ACTIVE.

Example: Delete a pool

Normal response codes
204
Error response codes
badRequest (400), unauthorized (401), conflict (409), overLimit (413), Internal-server-error (500), serviceUnavailable (503)

This operation does not accept a request body and does not return a response body.

GET
/v2.0/lbaas/pools/​{pool_id}​/members
List pool members

Lists members of a specified 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.

This operation does not require a request body.

This operation returns a response body. It returns a (potentially empty) list. Each element in the list is a member that can contain the following attributes:

  • id

  • tenant_id

  • address

  • protocol_port

  • weight

  • subnet_id

  • admin_state_up

Example: List pool members

Normal response codes
200
Error response codes
unauthorized (401), serviceUnavailable (503), Internal-server-error (500)
Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the member.

tenant_id plain csapi:uuid

The ID of the tenant who owns the member. Only administrative users can specify a tenant ID other than their own.

subnet_id plain csapi:uuid

Subnet in which to access this member.

address plain xsd:ip

The IP address of the member.

protocol_port plain xsd:int

The port where the application is hosted.

weight plain xsd:int

Weight of member.

admin_state_up plain xsd:boolean

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

status plain xsd:string

The status of the member. Indicates whether the member is operational.

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

This operation does not accept a request body.

POST
/v2.0/lbaas/pools/​{pool_id}​/members
Add member to pool

Adds a member to a pool.

 

This operation provisions a new member and adds it to a pool based on the configuration defined in the request object. After the request is validated and progress has started on the provisioning process, a response object is returned. The object contains a unique identifier.

The caller of this operation must specify the following pool attributes, at a minimum:

  • tenant_id. Only required if the caller has an administrative role and wants 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 that the member is listening to receive traffic.

Some attributes receive default values if not specified in the request:

  • admin_state_up. The default is true.

  • weight. The default is 1.

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

If the request fails due to incorrect data, the response returns an HTTP 400 (Bad Request) error with information about reason for the failure. 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.

Users with an administrative role can create members on behalf of other tenants by specifying a tenant_id attribute that is different than their own.

To update a member, the load balancer must have a provisioning_status of ACTIVE.

Normal response codes
201
Error response codes
unauthorized (401), itemNotFound (404), conflict (409), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Request parameters
Parameter Style Type Description
tenant_id plain csapi:uuid

The ID of the tenant who owns the member. Only administrative users can specify a tenant ID other than their own.

address plain xsd:ip

The IP address of the member.

protocol_port plain xsd:int

The port where the application is hosted.

subnet_id (Optional) plain xsd:int

If you omit this parameter, LBaaS uses the vip_subnet_id parameter value for the subnet ID.

Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the member.

tenant_id plain csapi:uuid

The ID of the tenant who owns the member. Only administrative users can specify a tenant ID other than their own.

subnet_id (Optional) plain csapi:uuid

Subnet in which to access this member.

address plain xsd:ip

The IP address of the member.

protocol_port plain xsd:int

The port where the application is hosted.

weight (Optional) plain xsd:int

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 plain xsd:boolean

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

status plain xsd:string

The status of the member. Indicates whether the member is operational.

{
    "member": {
        "address": "10.0.0.8",
        "admin_state_up": true,
        "protocol_port": "80",
        "subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2",
        "weight": "1"
    }
}
{
    "member": {
        "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
    }
}
GET
/v2.0/lbaas/pools/​{pool_id}​/members/​{member_id}​
Show pool member details

Shows details for a specified pool member.

 

This operation returns a member object identified by member_id that belongs to a pool object identified by pool_id. If the user is not an administrative user and the pool or member object does not belong to her tenant account, she receives a 403 (Forbidden) error.

This operation does not require a request body.

This operation returns a response body. On success, the returned element is a pool that can contain the following attributes:

  • id

  • tenant_id

  • address

  • protocol_port

  • weight

  • subnet_id

  • admin_state_up

Example: Show pool member details

Normal response codes
200
Error response codes
unauthorized (401), forbidden (403), itemNotFound (404), conflict (409), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the member.

tenant_id plain csapi:uuid

The ID of the tenant who owns the member. Only administrative users can specify a tenant ID other than their own.

subnet_id plain csapi:uuid

Subnet in which to access this member.

address plain xsd:ip

The IP address of the member.

protocol_port plain xsd:int

The port where the application is hosted.

weight plain xsd:int

Weight of member.

admin_state_up plain xsd:boolean

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

status plain xsd:string

The status of the member. Indicates whether the member is operational.

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

This operation does not accept a request body.

PUT
/v2.0/lbaas/pools/​{pool_id}​/members/​{member_id}​
Update pool member

Updates a specified member of a pool.

 

This operation updates the attributes of the specified pool. Upon successful validation of the request, the service returns a 200 (OK) response code.

The update operation allows the caller to change one or more of the following pool attributes:

  • weight

  • admin_state_up

Note: You cannot update these attributes: The member ID, tenant_id, address, protocol_port, and subnet_id. If you attempt to update any of these attributes, a 422 (Immutable) fault is returned.

Note: You cannot update a member if the attached load balancer does not have a provisioning_status of ACTIVE.

Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Request parameters
Parameter Style Type Description
admin_state_up plain xsd:boolean

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

Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the member.

tenant_id plain csapi:uuid

The ID of the tenant who owns the member. Only administrative users can specify a tenant ID other than their own.

subnet_id plain csapi:uuid

Subnet in which to access this member.

address plain xsd:ip

The IP address of the member.

protocol_port plain xsd:int

The port where the application is hosted.

weight plain xsd:int

Weight of member.

admin_state_up plain xsd:boolean

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

status plain xsd:string

The status of the member. Indicates whether the member is operational.

{
    "member": {
        "admin_state_up": false,
        "weight": 5
    }
}
{
    "member": {
        "address": "10.0.0.8",
        "admin_state_up": false,
        "id": "9a7aff27-fd41-4ec1-ba4c-3eb92c629313",
        "protocol_port": 80,
        "subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2",
        "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c",
        "weight": 5
    }
}
DELETE
/v2.0/lbaas/pools/​{pool_id}​/members/​{member_id}​
Remove member from pool

Removes a member from a pool.

 

This operation removes the specified member and its associated configuration from the tenant account. Any and all configuration data is immediately purged and is not recoverable.

This operation does not require a request body.

This operation does not return a response body.

A member cannot be deleted if the attached load balancer does not have a provisioning_status of ACTIVE.

Example: Remove a member from a pool

Normal response codes
204
Error response codes
badRequest (400), unauthorized (401), conflict (409), overLimit (413), Internal-server-error (500), serviceUnavailable (503)

This operation does not accept a request body and does not return a response body.

POST
/v2.0/lbaas/healthmonitors
Create health monitor

Creates a health monitor.

 

This operation provisions a new health monitor based on the configuration defined in the request object. After the request is validated and progress has started on the provisioning process, a response object is returned. The object contains a unique identifier.

The caller of this operation must specify these health monitor attributes, at a minimum:

  • tenant_id. Only required if the caller has an administrative role and wants to create a health monitor for another tenant.

  • type. The type of health monitor. Must be one of TCP, HTTP, HTTPS

  • delay. The interval in seconds between health checks.

  • timeout. The time in seconds that a health check times out.

  • max_retries. Number of failed health checks before marked as OFFLINE.

  • pool_id. The pool that this health monitor will monitor.

Some attributes will receive default values if not specified in the request and are only useful when health monitor type of HTTP(S) is specified:

  • http_method. The default is GET.

  • url_path. The default is /.

  • expected_codes. The expected http status codes to get from a successful health check. Default is 200.

  • admin_state_up. The default is true.

If the request cannot be fulfilled due to insufficient data or data that is not valid, an HTTP 400 (Bad Request) error response is returned with information regarding the nature of the failure in the response body. Failures in the validation process are non-recoverable and require the caller to correct the cause of the failure and POST 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.

Users with an administrative role can create health monitors on behalf of other tenants by specifying a tenant_id attribute different than their own.

To update a health monitor, the load balancer to which it is being attached must have an ACTIVE provisioning status.

Example: Create a health monitor

Normal response codes
201
Error response codes
unauthorized (401), itemNotFound (404), conflict (409), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Request parameters
Parameter Style Type Description
tenant_id plain csapi:uuid

The ID of the tenant who owns the VIP. Only administrative users can specify a tenant ID other than their own.

type plain xsd:string

The type of probe that is sent by the load balancer to verify the member state. A valid value is PING, TCP, HTTP, or HTTPS.

delay plain xsd:int

The time, in seconds, between sending probes to members.

timeout plain xsd:int

Time in seconds to timeout each probe.

max_retries plain xsd:int

Maximum consecutive health probe tries.

url_path (Optional) plain xsd:string

Path portion of URI that will be probed if type is HTTP(S).

expected_codes (Optional) plain xsd:string

Expected HTTP codes for a passing HTTP(S) monitor.

Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the VIP.

tenant_id plain csapi:uuid

The ID of the tenant who owns the VIP. Only administrative users can specify a tenant ID other than their own.

type plain xsd:string

The type of probe sent by the load balancer to verify the member state, which is PING, TCP, HTTP, or HTTPS.

delay plain xsd:int

The time, in seconds, between sending probes to members.

timeout plain xsd:int

The maximum number of seconds for a monitor to wait for a connection to be established before it times out. This value must be less than the delay value.

max_retries plain xsd:int

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) plain xsd:string

The HTTP method that the monitor uses for requests.

url_path (Optional) plain xsd:string

The HTTP path of the request sent by the monitor to test the health of a member. Must be a string beginning with a forward slash (/).

expected_codes (Optional) plain xsd:string

Expected HTTP codes for a passing HTTP(S) monitor.

admin_state_up (Optional) plain xsd:boolean

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

status plain xsd:string

The status of the health monitor. Indicates whether the health monitor is operational.

{
    "healthmonitor": {
        "admin_state_up": true,
        "delay": "1",
        "expected_codes": "200,201,202",
        "http_method": "GET",
        "max_retries": 5,
        "pool_id": "74aa2010-a59f-4d35-a436-60a6da882819",
        "timeout": 1,
        "type": "HTTP",
        "url_path": "/index.html"
    }
}
{
    "healthmonitor": {
        "admin_state_up": true,
        "delay": 1,
        "expected_codes": "200,201,202",
        "http_method": "GET",
        "id": "0a9ac99d-0a09-4b18-8499-a0796850279a",
        "max_retries": 5,
        "pools": [
            {
                "id": "74aa2010-a59f-4d35-a436-60a6da882819"
            }
        ],
        "tenant_id": "6f3584d5754048a18e30685362b88411",
        "timeout": 1,
        "type": "HTTP",
        "url_path": "/index.html"
    }
}
GET
/v2.0/lbaas/healthmonitors
List health monitors

Lists health monitors.

 

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

This operation does not require a request body.

This operation returns a response body. It returns a (potentially empty) list, each element in the list is a health monitor that can contain the following attributes:

  • id

  • tenant_id

  • type

  • delay

  • timeout

  • max_retries

  • http_method

  • url_path

  • expected_codes

  • admin_state_up

  • pool_id

  • pools

Example: List health monitors

Normal response codes
200
Error response codes
unauthorized (401), Internal-server-error (500), serviceUnavailable (503)
Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the VIP.

tenant_id plain csapi:uuid

The ID of the tenant who owns the VIP. Only administrative users can specify a tenant ID other than their own.

type plain xsd:string

The type of probe sent by the load balancer to verify the member state, which is PING, TCP, HTTP, or HTTPS.

delay plain xsd:int

The time, in seconds, between sending probes to members.

timeout plain xsd:int

The maximum number of seconds for a monitor to wait for a connection to be established before it times out. This value must be less than the delay value.

max_retries plain xsd:int

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) plain xsd:string

The HTTP method that the monitor uses for requests.

url_path (Optional) plain xsd:string

The HTTP path of the request sent by the monitor to test the health of a member. Must be a string beginning with a forward slash (/).

expected_codes (Optional) plain xsd:string

Expected HTTP codes for a passing HTTP(S) monitor.

admin_state_up (Optional) plain xsd:boolean

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

status plain xsd:string

The status of the health monitor. Indicates whether the health monitor is operational.

{
    "healthmonitors": [
        {
            "admin_state_up": true,
            "delay": 1,
            "expected_codes": "200,201,202",
            "http_method": "GET",
            "id": "0a9ac99d-0a09-4b18-8499-a0796850279a",
            "max_retries": 5,
            "pools": [
                {
                    "id": "74aa2010-a59f-4d35-a436-60a6da882819"
                }
            ],
            "tenant_id": "6f3584d5754048a18e30685362b88411",
            "timeout": 1,
            "type": "HTTP",
            "url_path": "/index.html"
        }
    ]
}

This operation does not accept a request body.

GET
/v2.0/lbaas/healthmonitors/​{health_monitor_id}​
Show health monitor details

Shows details for a specified health monitor.

 

This operation returns a health monitor object identified by healthmonitor_id. If the user is not an administrative user, and the health monitor object does not belong to her tenant account, she receives a 403 (Forbidden) error.

This operation does not require a request body.

This operation returns a response body. On success, the returned element is a health monitor that can contain the following attributes:

  • id

  • tenant_id

  • type

  • delay

  • timeout

  • max_retries

  • http_method

  • url_path

  • expected_codes

  • admin_state_up

  • pool_id

  • pools

Example: Show health monitor details

Normal response codes
200
Error response codes
unauthorized (401), forbidden (403), itemNotFound (404), conflict (409), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the VIP.

tenant_id plain csapi:uuid

The ID of the tenant who owns the VIP. Only administrative users can specify a tenant ID other than their own.

type plain xsd:string

The type of probe sent by the load balancer to verify the member state, which is PING, TCP, HTTP, or HTTPS.

delay plain xsd:int

The time, in seconds, between sending probes to members.

timeout plain xsd:int

The maximum number of seconds for a monitor to wait for a connection to be established before it times out. This value must be less than the delay value.

max_retries plain xsd:int

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) plain xsd:string

The HTTP method that the monitor uses for requests.

url_path (Optional) plain xsd:string

The HTTP path of the request sent by the monitor to test the health of a member. Must be a string beginning with a forward slash (/).

expected_codes (Optional) plain xsd:string

Expected HTTP codes for a passing HTTP(S) monitor.

admin_state_up (Optional) plain xsd:boolean

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

status plain xsd:string

The status of the health monitor. Indicates whether the health monitor is operational.

{
    "healthmonitor": {
        "admin_state_up": true,
        "delay": 1,
        "expected_codes": "200,201,202",
        "http_method": "GET",
        "id": "0a9ac99d-0a09-4b18-8499-a0796850279a",
        "max_retries": 5,
        "pools": [
            {
                "id": "74aa2010-a59f-4d35-a436-60a6da882819"
            }
        ],
        "tenant_id": "6f3584d5754048a18e30685362b88411",
        "timeout": 1,
        "type": "HTTP",
        "url_path": "/index.html"
    }
}

This operation does not accept a request body.

PUT
/v2.0/lbaas/healthmonitors/​{health_monitor_id}​
Update health monitor

Updates a specified health monitor.

 

This operation updates the attributes of the specified health monitor. Upon successful validation of the request, the service returns the 202 (Accepted) response code.

The update operation enables you to change one or more health monitor attributes:

  • delay

  • timeout

  • max_retries

  • http_method

  • url_path

  • expected_codes

  • admin_state_up

Note: The health monitor's ID, tenant_id, pool_id, and type are immutable attributes and cannot be updated. Supplying an unsupported attribute results in a 422 (Immutable) fault.

Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), overLimit (413), Internal-server-error (500), serviceUnavailable (503)
Request parameters
Parameter Style Type Description
delay plain xsd:int

The time, in seconds, between sending probes to members.

url_path plain xsd: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 (/).

Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the VIP.

tenant_id plain csapi:uuid

The ID of the tenant who owns the VIP. Only administrative users can specify a tenant ID other than their own.

type plain xsd:string

The type of probe sent by the load balancer to verify the member state, which is PING, TCP, HTTP, or HTTPS.

delay plain xsd:int

The time, in seconds, between sending probes to members.

timeout plain xsd:int

The maximum number of seconds for a monitor to wait for a connection to be established before it times out. This value must be less than the delay value.

max_retries plain xsd:int

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) plain xsd:string

The HTTP method that the monitor uses for requests.

url_path (Optional) plain xsd:string

The HTTP path of the request sent by the monitor to test the health of a member. Must be a string beginning with a forward slash (/).

expected_codes (Optional) plain xsd:string

Expected HTTP codes for a passing HTTP(S) monitor.

admin_state_up (Optional) plain xsd:boolean

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

status plain xsd:string

The status of the health monitor. Indicates whether the health monitor is operational.

{
    "healthmonitor": {
        "admin_state_up": false,
        "delay": "2",
        "expected_codes": "200",
        "http_method": "POST",
        "max_retries": 2,
        "timeout": 2,
        "url_path": "/page.html"
    }
}
{
    "healthmonitor": {
        "admin_state_up": false,
        "delay": 2,
        "expected_codes": "200",
        "http_method": "POST",
        "id": "0a9ac99d-0a09-4b18-8499-a0796850279a",
        "max_retries": 2,
        "pools": [
            {
                "id": "74aa2010-a59f-4d35-a436-60a6da882819"
            }
        ],
        "tenant_id": "6f3584d5754048a18e30685362b88411",
        "timeout": 2,
        "type": "HTTP",
        "url_path": "/page.html"
    }
}
DELETE
/v2.0/lbaas/healthmonitors/​{health_monitor_id}​
Remove health monitor

Removes a specified health monitor.

 

This operation removes the specified health monitor and its associated configuration from the tenant account. Any and all configuration data is immediately purged and is not recoverable.

This operation does not require a request body.

This operation does not return a response body.

You cannot delete a health monitor if the attached load balancer does not have a provisioning_status of ACTIVE.

Example: Delete a health monitor

Normal response codes
204
Error response codes
badRequest (400), unauthorized (401), conflict (409), overLimit (413), Internal-server-error (500), serviceUnavailable (503)

This operation does not accept a request body and does not return a response body.

Subnet pools extension (subnetpools)

Manages subnet pools

GET
/v2.0/subnetpools
List subnet pools

Lists subnet pools to which the specified 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
unauthorized (401)
Response parameters
Parameter Style Type Description
subnetpools plain xsd:string

A subnetpools object.

min_prefixlen plain xsd:int

The smallest prefix that can be allocated from a subnet pool.

address_scope_id plain csapi:uuid

The address scope.

default_prefixlen plain xsd:int

The size of the prefix to allocate when the cidr or prefixlen attributes are not specified when you create the subnet.

id plain csapi:uuid

The ID of the subnet pool.

max_prefixlen plain xsd:int

The maximum prefix size that can be allocated from the subnet pool.

name plain xsd:string

The subnet pool name.

default_quota plain xsd:int

A per-tenant quota on the prefix space that can be allocated from the subnet pool for tenant subnets. 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 plain xsd:string

The ID of the tenant who owns the subnet pool.

prefixes plain xsd:dict

A list of subnet prefixes that are assigned to the subnet pool. The API merges adjacent prefixes and treats them as a single prefix.

ip_version plain xsd:int

The IP address family of the list of prefixes passed to the prefixes attribute.

shared plain xsd:bool

Indicates whether this subnet pool is shared across all tenants.

{
    "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,
            "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,
            "tenant_id": "9fadcee8aa7c40cdb2114fff7d569c08",
            "prefixes": [
                "10.10.0.0/21",
                "192.168.0.0/16"
            ],
            "ip_version": 4,
            "shared": false
        }
    ]
}

This operation does not accept a request body.

POST
/v2.0/subnetpools
Create subnet pool

Creates a subnet pool.

 
Normal response codes
201
Error response codes
badRequest (400), unauthorized (401), forbidden (403), itemNotFound (404)
Request parameters
Parameter Style Type Description
subnetpool plain xsd:string

A subnetpool object.

name plain xsd:string

A name for the subnet pool.

address_scope_id (Optional) plain csapi:uuid

An address scope to assign to the subnet pool.

prefixes plain xsd:dict

A list of subnet prefixes to assign to the subnet pool. The API merges adjacent prefixes and treats them as a single prefix.

Ensure that each subnet prefix is unique among all subnet prefixes in all subnet pools that are associated with the specified address scope.

default_prefixlen (Optional) plain xsd:int

The size of the prefix to allocate when the cidr or prefixlen attributes are not specified when you create the subnet. Default is min_prefixlen.

min_prefixlen (Optional) plain xsd:int

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.

max_prefixlen (Optional) plain xsd:int

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.

default_quota (Optional) plain xsd:int

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 (Optional) plain csapi:uuid

The ID of the tenant who owns the subnet pool. Only administrative users can specify a tenant ID other than their own. You cannot change this value through authorization policies.

shared (Optional) plain xsd:bool

Admin-only. Indicates whether this subnet pool is shared across all tenants.

Response parameters
Parameter Style Type Description
subnetpool plain xsd:string

A subnetpool object.

min_prefixlen plain xsd:int

The smallest prefix that can be allocated from a subnet pool.

address_scope_id plain csapi:uuid

The address scope.

default_prefixlen plain xsd:int

The size of the prefix to allocate when the cidr or prefixlen attributes are not specified when you create the subnet.

id plain csapi:uuid

The ID of the subnet pool.

max_prefixlen plain xsd:int

The maximum prefix size that can be allocated from the subnet pool.

name plain xsd:string

The subnet pool name.

default_quota plain xsd:int

A per-tenant quota on the prefix space that can be allocated from the subnet pool for tenant subnets. 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 plain xsd:string

The ID of the tenant who owns the subnet pool.

prefixes plain xsd:dict

A list of subnet prefixes that are assigned to the subnet pool. The API merges adjacent prefixes and treats them as a single prefix.

ip_version plain xsd:int

The IP address family of the list of prefixes passed to the prefixes attribute.

shared plain xsd:bool

Indicates whether this subnet pool is shared across all tenants.

{
    "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"
    }
}
{
    "subnetpool": {
        "min_prefixlen": "24",
        "address_scope_id": null,
        "default_prefixlen": "25",
        "id": "f49a1319-423a-4ee6-ba54-1d95a4f6cc68",
        "max_prefixlen": "30",
        "name": "my-subnet-pool",
        "default_quota": null,
        "tenant_id": "9fadcee8aa7c40cdb2114fff7d569c08",
        "prefixes": [
            "10.10.0.0/21",
            "192.168.0.0/16"
        ],
        "ip_version": 4,
        "shared": false
    }
}
GET
/v2.0/subnetpools/​{subnetpool_id}​
Show subnet pool

Shows information for a specified subnet pool.

 

Use the fields query parameter to filter the results.

Normal response codes
200
Error response codes
unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
subnetpool_id URI csapi:UUID

The UUID for the subnet pool of interest to you.

Response parameters
Parameter Style Type Description
subnetpool plain xsd:string

A subnetpool object.

min_prefixlen plain xsd:int

The smallest prefix that can be allocated from a subnet pool.

address_scope_id plain csapi:uuid

The address scope.

default_prefixlen plain xsd:int

The size of the prefix to allocate when the cidr or prefixlen attributes are not specified when you create the subnet.

id plain csapi:uuid

The ID of the subnet pool.

max_prefixlen plain xsd:int

The maximum prefix size that can be allocated from the subnet pool.

name plain xsd:string

The subnet pool name.

default_quota plain xsd:int

A per-tenant quota on the prefix space that can be allocated from the subnet pool for tenant subnets. 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 plain xsd:string

The ID of the tenant who owns the subnet pool.

prefixes plain xsd:dict

A list of subnet prefixes that are assigned to the subnet pool. The API merges adjacent prefixes and treats them as a single prefix.

ip_version plain xsd:int

The IP address family of the list of prefixes passed to the prefixes attribute.

shared plain xsd:bool

Indicates whether this subnet pool is shared across all tenants.

{
    "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,
        "tenant_id": "9fadcee8aa7c40cdb2114fff7d569c08",
        "prefixes": [
            "2001:db8:0:2::/64",
            "2001:db8::/63"
        ],
        "ip_version": 6,
        "shared": false
    }
}

This operation does not accept a request body.

PUT
/v2.0/subnetpools/​{subnetpool_id}​
Update subnet pool

Updates a specified subnet pool.

 
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), forbidden (403), itemNotFound (404)
Request parameters
Parameter Style Type Description
subnetpool_id URI csapi:UUID

The UUID for the subnet pool of interest to you.

subnetpool plain xsd:string

A subnetpool object.

name plain xsd:string

A name for the subnet pool.

address_scope_id (Optional) plain csapi:uuid

An address scope to assign to the subnet pool.

prefixes plain xsd:dict

A list of subnet prefixes to assign to the subnet pool. The API merges adjacent prefixes and treats them as a single prefix.

To update the subnet prefixes, pass a list that contains the existing set of prefixes and the new set of prefixes. You cannot shrink the prefix list of a subnet pool. You can only add prefixes to it to expand it.

Ensure that each subnet prefix is unique among all subnet prefixes in all subnet pools that are associated with the specified address scope.

default_prefixlen (Optional) plain xsd:int

The size of the prefix to allocate when the cidr or prefixlen attributes are not specified when you create the subnet. Default is min_prefixlen.

min_prefixlen (Optional) plain xsd:int

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.

max_prefixlen (Optional) plain xsd:int

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.

default_quota (Optional) plain xsd:int

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.

Updating this parameter has no effect on existing subnet allocations. The existing subnet allocations for each tenant are counted against the updated prefix space quota.

tenant_id (Optional) plain csapi:uuid

The ID of the tenant who owns the subnet pool. Only administrative users can specify a tenant ID other than their own. You cannot change this value through authorization policies.

Response parameters
Parameter Style Type Description
subnetpool plain xsd:string

A subnetpool object.

min_prefixlen plain xsd:int

The smallest prefix that can be allocated from a subnet pool.

address_scope_id plain csapi:uuid

The address scope.

default_prefixlen plain xsd:int

The size of the prefix to allocate when the cidr or prefixlen attributes are not specified when you create the subnet.

id plain csapi:uuid

The ID of the subnet pool.

max_prefixlen plain xsd:int

The maximum prefix size that can be allocated from the subnet pool.

name plain xsd:string

The subnet pool name.

default_quota plain xsd:int

A per-tenant quota on the prefix space that can be allocated from the subnet pool for tenant subnets. 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 plain xsd:string

The ID of the tenant who owns the subnet pool.

prefixes plain xsd:dict

A list of subnet prefixes that are assigned to the subnet pool. The API merges adjacent prefixes and treats them as a single prefix.

ip_version plain xsd:int

The IP address family of the list of prefixes passed to the prefixes attribute.

shared plain xsd:bool

Indicates whether this subnet pool is shared across all tenants.

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

 

The operation fails if any subnets allocated from the subnet pool are still in use.

Normal response codes
204
Error response codes
unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
subnetpool_id URI csapi:UUID

The UUID for the subnet pool of interest to you.

This operation does not accept a request body and does not return a response body.

Virtual-Private-Network-as-a-Service (VPNaaS) 2.0 (CURRENT)

The VPNaaS extension enables OpenStack tenants to extend private networks across the public telecommunication infrastructure.

This initial implementation of the VPNaaS extension provides:

  • Site-to-site VPN that connects two private networks.

  • Multiple VPN connections per tenant.

  • IKEv1 policy support with 3des, aes-128, aes-256, or aes-192 encryption.

  • IPSec policy support with 3des, aes-128, aes-192, or aes-256 encryption, sha1 authentication, ESP, AH, or AH-ESP transform protocol, and tunnel or transport mode encapsulation.

  • Dead Peer Detection (DPD) with hold, clear, restart, disabled, or restart-by-peer actions.

This extension introduces these resources:

  • service. A parent object that associates VPN with a specific subnet and router.

  • ikepolicy. The Internet Key Exchange (IKE) policy that identifies the authentication and encryption algorithm to use during phase one and two negotiation of a VPN connection.

  • ipsecpolicy. The IP security policy that specifies the authentication and encryption algorithm and encapsulation mode to use for the established VPN connection.

  • ipsec-site-connection. Details for the site-to-site IPsec connection, including the peer CIDRs, MTU, authentication mode, peer address, DPD settings, and status.

GET
/v2.0/vpn/vpnservices
List VPN services

Lists VPN services.

 

This operation lists all VPN services.

The list might be empty.

Normal response codes
200
Error response codes
unauthorized (401), forbidden (403)
Response parameters
Parameter Style Type Description
vpnservices plain xsd:list

VPN service objects.

router_id plain csapi:uuid

ID of the router into which the VPN service is inserted.

status plain xsd:string

Indicates whether IPSec VPN service is currently operational. Possible values are ACTIVE, DOWN, BUILD, ERROR, PENDING_CREATE, PENDING_UPDATE, and PENDING_DELETE.

name plain xsd:string

Human-readable name for the VPN service. Does not have to be unique.

admin_state_up plain xsd:boolean

The administrative state of the VPN service, which is up (true) or down (false). If down, the port does not forward packets.

subnet_id plain csapi:uuid

The subnet where the tenant wants the VPN service.

tenant_id plain csapi:uuid

Owner of the VPN service. Only administrative users can specify a tenant ID other than their own.

id plain csapi:uuid

The unique ID for the VPN service.

description plain xsd:string

Human-readable description for the VPN service.

{
    "vpnservices": [
        {
            "router_id": "ec8619be-0ba8-4955-8835-3b49ddb76f89",
            "status": "PENDING_CREATE",
            "name": "myservice",
            "admin_state_up": true,
            "subnet_id": "f4fb4528-ed93-467c-a57b-11c7ea9f963e",
            "tenant_id": "ccb81365fe36411a9011e90491fe1330",
            "id": "9faaf49f-dd89-4e39-a8c6-101839aa49bc",
            "description": ""
        }
    ]
}

This operation does not accept a request body.

POST
/v2.0/vpn/vpnservices
Create VPN service

Creates a VPN service.

 

Creates a VPN service object. The service is associated with a router and a local (private) subnet. After the service is created, it can contain multiple VPN connections.

Example:

Normal response codes
201
Error response codes
badRequest (400), unauthorized (401)
Request parameters
Parameter Style Type Description
vpnservice plain xsd:dict

VPN service object.

name (Optional) plain xsd:string

Human-readable name for the VPN service. Does not have to be unique.

description (Optional) plain xsd:string

Human-readable description for the VPN service.

admin_state_up (Optional) plain xsd:boolean

The administrative state of the VPN service, which is up (true) or down (false). If down, connections on service are not active.

vpnservice plain xsd:dict

VPN service object.

tenant_id (Optional) plain csapi:uuid

Owner of the VPN service. Only administrative users can specify a tenant ID other than their own.

subnet_id plain csapi:uuid

The subnet where the tenant wants the VPN service.

router_id plain csapi:uuid

Router ID to which the VPN service is inserted.

Response parameters
Parameter Style Type Description
vpnservice plain xsd:dict

VPN service object.

router_id plain csapi:uuid

ID of the router into which the VPN service is inserted.

status plain xsd:string

Indicates whether IPSec VPN service is currently operational. Possible values are ACTIVE, DOWN, BUILD, ERROR, PENDING_CREATE, PENDING_UPDATE, and PENDING_DELETE.

name plain xsd:string

Human-readable name for the VPN service. Does not have to be unique.

admin_state_up plain xsd:boolean

The administrative state of the VPN service, which is up (true) or down (false). If down, the port does not forward packets.

subnet_id plain csapi:uuid

The subnet where the tenant wants the VPN service.

tenant_id plain csapi:uuid

Owner of the VPN service. Only administrative users can specify a tenant ID other than their own.

id plain csapi:uuid

The unique ID for the VPN service.

description plain xsd:string

Human-readable description for the VPN service.

{
    "vpnservice": {
        "subnet_id": "f4fb4528-ed93-467c-a57b-11c7ea9f963e",
        "router_id": "ec8619be-0ba8-4955-8835-3b49ddb76f89",
        "name": "myservice",
        "admin_state_up": true
    }
}
{
    "vpnservice": {
        "router_id": "ec8619be-0ba8-4955-8835-3b49ddb76f89",
        "status": "PENDING_CREATE",
        "name": "myservice",
        "admin_state_up": true,
        "subnet_id": "f4fb4528-ed93-467c-a57b-11c7ea9f963e",
        "tenant_id": "ccb81365fe36411a9011e90491fe1330",
        "id": "9faaf49f-dd89-4e39-a8c6-101839aa49bc",
        "description": ""
    }
}
GET
/v2.0/vpn/vpnservices/​{service_id}​
Show VPN service details

Shows details for a specified VPN service.

 

Shows details for a specified VPN service. If the user is not an administrative user and the VPN service object does not belong to the user's tenant account, a 403 (Forbidden) error is returned.

Normal response codes
200
Error response codes
unauthorized (401), forbidden (403), itemNotFound (404)
Request parameters
Parameter Style Type Description
service_id URI csapi:UUID The UUID for the VPN service.
Response parameters
Parameter Style Type Description
vpnservice plain xsd:dict

VPN service object.

router_id plain csapi:uuid

ID of the router into which the VPN service is inserted.

status plain xsd:string

Indicates whether IPSec VPN service is currently operational. Possible values are ACTIVE, DOWN, BUILD, ERROR, PENDING_CREATE, PENDING_UPDATE, and PENDING_DELETE.

name plain xsd:string

Human-readable name for the VPN service. Does not have to be unique.

admin_state_up plain xsd:boolean

The administrative state of the VPN service, which is up (true) or down (false). If down, the port does not forward packets.

subnet_id plain csapi:uuid

The subnet where the tenant wants the VPN service.

tenant_id plain csapi:uuid

Owner of the VPN service. Only administrative users can specify a tenant ID other than their own.

id plain csapi:uuid

The unique ID for the VPN service.

description plain xsd:string

Human-readable description for the VPN service.

{
    "vpnservice": {
        "router_id": "ec8619be-0ba8-4955-8835-3b49ddb76f89",
        "status": "PENDING_CREATE",
        "name": "myservice",
        "admin_state_up": true,
        "subnet_id": "f4fb4528-ed93-467c-a57b-11c7ea9f963e",
        "tenant_id": "ccb81365fe36411a9011e90491fe1330",
        "id": "9faaf49f-dd89-4e39-a8c6-101839aa49bc",
        "description": ""
    }
}

This operation does not accept a request body.

PUT
/v2.0/vpn/vpnservices/​{service_id}​
Update VPN service

Updates a specified VPN service.

 

This operation updates the attributes of a specified VPN service. To update a service, the service status cannot be a PENDING_* status.

Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
service_id URI csapi:UUID The UUID for the VPN service.
vpnservice plain xsd:dict

VPN service object.

vpnservice plain xsd:dict

VPN service object.

name (Optional) plain xsd:string

Human-readable name for the VPN service. Does not have to be unique.

description (Optional) plain xsd:string

Human-readable description for the VPN service.

admin_state_up (Optional) plain xsd:boolean

The administrative state of the VPN service, which is up (true) or down (false). If down, connections on service are not active.

Response parameters
Parameter Style Type Description
vpnservice plain xsd:dict

VPN service object.

router_id plain csapi:uuid

ID of the router into which the VPN service is inserted.

status plain xsd:string

Indicates whether IPSec VPN service is currently operational. Possible values are ACTIVE, DOWN, BUILD, ERROR, PENDING_CREATE, PENDING_UPDATE, and PENDING_DELETE.

name plain xsd:string

Human-readable name for the VPN service. Does not have to be unique.

admin_state_up plain xsd:boolean

The administrative state of the VPN service, which is up (true) or down (false). If down, the port does not forward packets.

subnet_id plain csapi:uuid

The subnet where the tenant wants the VPN service.

tenant_id plain csapi:uuid

Owner of the VPN service. Only administrative users can specify a tenant ID other than their own.

id plain csapi:uuid

The unique ID for the VPN service.

description plain xsd:string

Human-readable description for the VPN service.

{
    "vpnservice": {
        "description": "Updated description"
    }
}
{
    "vpnservice": {
        "router_id": "881b7b30-4efb-407e-a162-5630a7af3595",
        "status": "ACTIVE",
        "name": "myvpn",
        "admin_state_up": true,
        "subnet_id": "25f8a35c-82d5-4f55-a45b-6965936b33f6",
        "tenant_id": "26de9cd6cae94c8cb9f79d660d628e1f",
        "id": "41bfef97-af4e-4f6b-a5d3-4678859d2485",
        "description": "Updated description"
    }
}
DELETE
/v2.0/vpn/vpnservices/​{service_id}​
Remove VPN service

Removes a specified VPN service.

 

This operation removes a specified VPN service. If the service has connections, the request is rejected.

Normal response codes
204
Error response codes
unauthorized (401), itemNotFound (404), conflict (409)
Request parameters
Parameter Style Type Description
service_id URI csapi:UUID The UUID for the VPN service.

This operation does not accept a request body and does not return a response body.

GET
/v2.0/vpn/ikepolicies
List IKE policies

Lists IKE policies.

 

This operation lists all IKE policies.

Normal response codes
200
Error response codes
unauthorized (401), forbidden (403)
Response parameters
Parameter Style Type Description
ikepolicies plain xsd:list

IKE policy objects.

id plain csapi:uuid

The unique ID for the IKE policy.

tenant_id plain csapi:uuid

Owner of the VPN service. Only administrative users can specify a tenant ID other than their own.

name plain xsd:string

Human-readable name for the IKE policy. Does not have to be unique.

description plain xsd:string

Human-readable description for the IKE policy.

auth_algorithm plain xsd:string

The authentication hash algorithm. A valid value is sha1, which is the default.

encryption_algorithm plain xsd:string

The encryption algorithm. A valid value is 3des, aes-128, aes-192, aes-256, and so on. Default is aes-128.

phase1_negotiation_mode plain xsd:string

The IKE mode. A valid value is main, which is the default.

pfs plain xsd:string

Perfect forward secrecy (PFS). A valid value is Group2, Group5, Group14, and so on. Default is Group5.

ike_version plain xsd:string

The IKE version. A valid value is v1 or v2. Default is v1.

lifetime plain xsd:dict

The lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime.

units plain xsd:string

Units for lifetime of the security association. Default is seconds.

value plain xsd:int

Lifetime value, as a positive integer. Default is 3600 seconds.

{
    "ikepolicies": [
        {
            "name": "ikepolicy1",
            "tenant_id": "ccb81365fe36411a9011e90491fe1330",
            "auth_algorithm": "sha1",
            "encryption_algorithm": "aes-256",
            "pfs": "group5",
            "phase1_negotiation_mode": "main",
            "lifetime": {
                "units": "seconds",
                "value": 3600
            },
            "ike_version": "v1",
            "id": "5522aff7-1b3c-48dd-9c3c-b50f016b73db",
            "description": ""
        }
    ]
}

This operation does not accept a request body.

POST
/v2.0/vpn/ikepolicies
Create IKE policy

Creates an IKE policy.

 

The IKE policy is used for phases one and two negotiation of the VPN connection. You can specify both the authentication and encryption algorithms for connections.

Normal response codes
201
Error response codes
badRequest (400), unauthorized (401)
Request parameters
Parameter Style Type Description
name (Optional) plain xsd:string

Human-readable name for the IKE policy. Does not have to be unique.

description (Optional) plain xsd:string

Human-readable description for the IKE policy.

auth_algorithm (Optional) plain xsd:string

The authentication hash algorithm. A valid value is sha1, which is the default.

encryption_algorithm (Optional) plain xsd:string

The encryption algorithm. A valid value is 3des, aes-128, aes-192, aes-256, and so on. Default is aes-128.

phase1_negotiation_mode (Optional) plain xsd:string

The IKE mode. A valid value is main, which is the default.

pfs (Optional) plain xsd:string

Perfect forward secrecy (PFS). A valid value is Group2, Group5, Group14, and so on. Default is Group5.

ike_version (Optional) plain xsd:string

The IKE version. A valid value is v1 or v2. Default is v1.

lifetime (Optional) plain xsd:dict

The lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime.

units (Optional) plain xsd:string

Units for lifetime of the security association. Default is seconds.

value (Optional) plain xsd:int

Lifetime value, as a positive integer. Default is 3600 seconds.

tenant_id plain csapi:uuid

Owner of the IKE policy. Only administrative users can specify a tenant ID other than their own.

Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the IKE policy.

tenant_id plain csapi:uuid

Owner of the VPN service. Only administrative users can specify a tenant ID other than their own.

name plain xsd:string

Human-readable name for the IKE policy. Does not have to be unique.

description plain xsd:string

Human-readable description for the IKE policy.

auth_algorithm plain xsd:string

The authentication hash algorithm. A valid value is sha1, which is the default.

encryption_algorithm plain xsd:string

The encryption algorithm. A valid value is 3des, aes-128, aes-192, aes-256, and so on. Default is aes-128.

phase1_negotiation_mode plain xsd:string

The IKE mode. A valid value is main, which is the default.

pfs plain xsd:string

Perfect forward secrecy (PFS). A valid value is Group2, Group5, Group14, and so on. Default is Group5.

ike_version plain xsd:string

The IKE version. A valid value is v1 or v2. Default is v1.

lifetime plain xsd:dict

The lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime.

units plain xsd:string

Units for lifetime of the security association. Default is seconds.

value plain xsd:int

Lifetime value, as a positive integer. Default is 3600 seconds.

{
    "ikepolicy": {
        "phase1_negotiation_mode": "main",
        "auth_algorithm": "sha1",
        "encryption_algorithm": "aes-128",
        "pfs": "group5",
        "lifetime": {
            "units": "seconds",
            "value": 7200
        },
        "ike_version": "v1",
        "name": "ikepolicy1"
    }
}
{
    "ikepolicy": {
        "name": "ikepolicy1",
        "tenant_id": "ccb81365fe36411a9011e90491fe1330",
        "auth_algorithm": "sha1",
        "encryption_algorithm": "aes-128",
        "pfs": "group5",
        "phase1_negotiation_mode": "main",
        "lifetime": {
            "units": "seconds",
            "value": 7200
        },
        "ike_version": "v1",
        "id": "5522aff7-1b3c-48dd-9c3c-b50f016b73db",
        "description": ""
    }
}
GET
/v2.0/vpn/ikepolicies/​{ikepolicy_id}​
Show IKE policies

Shows details for a specified IKE policy.

 

Shows the details for a specified IKE policy.

Normal response codes
200
Error response codes
unauthorized (401), forbidden (403), itemNotFound (404)
Request parameters
Parameter Style Type Description
ikepolicy_id URI csapi:UUID The UUID for the IKE policy.
Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the IKE policy.

tenant_id plain csapi:uuid

Owner of the VPN service. Only administrative users can specify a tenant ID other than their own.

name plain xsd:string

Human-readable name for the IKE policy. Does not have to be unique.

description plain xsd:string

Human-readable description for the IKE policy.

auth_algorithm plain xsd:string

The authentication hash algorithm. A valid value is sha1, which is the default.

encryption_algorithm plain xsd:string

The encryption algorithm. A valid value is 3des, aes-128, aes-192, aes-256, and so on. Default is aes-128.

phase1_negotiation_mode plain xsd:string

The IKE mode. A valid value is main, which is the default.

pfs plain xsd:string

Perfect forward secrecy (PFS). A valid value is Group2, Group5, Group14, and so on. Default is Group5.

ike_version plain xsd:string

The IKE version. A valid value is v1 or v2. Default is v1.

lifetime plain xsd:dict

The lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime.

units plain xsd:string

Units for lifetime of the security association. Default is seconds.

value plain xsd:int

Lifetime value, as a positive integer. Default is 3600 seconds.

{
    "ikepolicy": {
        "name": "ikepolicy1",
        "tenant_id": "ccb81365fe36411a9011e90491fe1330",
        "auth_algorithm": "sha1",
        "encryption_algorithm": "aes-256",
        "pfs": "group5",
        "phase1_negotiation_mode": "main",
        "lifetime": {
            "units": "seconds",
            "value": 3600
        },
        "ike_version": "v1",
        "id": "5522aff7-1b3c-48dd-9c3c-b50f016b73db",
        "description": ""
    }
}

This operation does not accept a request body.

PUT
/v2.0/vpn/ikepolicies/​{ikepolicy_id}​
Update IKE policy

Updates policy settings in a specified IKE policy.

 
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
ikepolicy_id URI csapi:UUID The UUID for the IKE policy.
name (Optional) plain xsd:string

Human-readable name for the IKE policy. Does not have to be unique.

description (Optional) plain xsd:string

Human-readable description for the IKE policy.

auth_algorithm (Optional) plain xsd:string

The authentication hash algorithm. A valid value is sha1, which is the default.

encryption_algorithm (Optional) plain xsd:string

The encryption algorithm. A valid value is 3des, aes-128, aes-192, aes-256, and so on. Default is aes-128.

phase1_negotiation_mode (Optional) plain xsd:string

The IKE mode. A valid value is main, which is the default.

pfs (Optional) plain xsd:string

Perfect forward secrecy (PFS). A valid value is Group2, Group5, Group14, and so on. Default is Group5.

ike_version (Optional) plain xsd:string

The IKE version. A valid value is v1 or v2. Default is v1.

lifetime (Optional) plain xsd:dict

The lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime.

units (Optional) plain xsd:string

Units for lifetime of the security association. Default is seconds.

value (Optional) plain xsd:int

Lifetime value, as a positive integer. Default is 3600 seconds.

Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the IKE policy.

tenant_id plain csapi:uuid

Owner of the VPN service. Only administrative users can specify a tenant ID other than their own.

name plain xsd:string

Human-readable name for the IKE policy. Does not have to be unique.

description plain xsd:string

Human-readable description for the IKE policy.

auth_algorithm plain xsd:string

The authentication hash algorithm. A valid value is sha1, which is the default.

encryption_algorithm plain xsd:string

The encryption algorithm. A valid value is 3des, aes-128, aes-192, aes-256, and so on. Default is aes-128.

phase1_negotiation_mode plain xsd:string

The IKE mode. A valid value is main, which is the default.

pfs plain xsd:string

Perfect forward secrecy (PFS). A valid value is Group2, Group5, Group14, and so on. Default is Group5.

ike_version plain xsd:string

The IKE version. A valid value is v1 or v2. Default is v1.

lifetime plain xsd:dict

The lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime.

units plain xsd:string

Units for lifetime of the security association. Default is seconds.

value plain xsd:int

Lifetime value, as a positive integer. Default is 3600 seconds.

{
    "ikepolicy": {
        "encryption_algorithm": "aes-256"
    }
}
{
    "ikepolicy": {
        "name": "ikepolicy1",
        "tenant_id": "ccb81365fe36411a9011e90491fe1330",
        "auth_algorithm": "sha1",
        "encryption_algorithm": "aes-256",
        "pfs": "group5",
        "phase1_negotiation_mode": "main",
        "lifetime": {
            "units": "seconds",
            "value": 3600
        },
        "ike_version": "v1",
        "id": "5522aff7-1b3c-48dd-9c3c-b50f016b73db",
        "description": ""
    }
}
DELETE
/v2.0/vpn/ikepolicies/​{ikepolicy_id}​
Remove IKE policy

Removes a specified IKE policy.

 

Removes the IKE policy specified in the request.

Normal response codes
204
Error response codes
unauthorized (401), itemNotFound (404), conflict (409)
Request parameters
Parameter Style Type Description
ikepolicy_id URI csapi:UUID The UUID for the IKE policy.

This operation does not accept a request body and does not return a response body.

GET
/v2.0/vpn/ipsecpolicies
List IPSec policies

Lists IPSec policies.

 

This operation lists all IPSec policies.

Normal response codes
200
Error response codes
unauthorized (401), forbidden (403)
Response parameters
Parameter Style Type Description
ipsecpolicies plain xsd:list

IPSec policy objects.

id plain csapi:uuid

The unique ID for the IPSec policy.

tenant_id plain csapi:uuid

Owner of the VPN service. Only administrative users can specify a tenant ID other than their own.

name plain xsd:string

Human-readable name for the IPSec policy. Does not have to be unique.

description plain xsd:string

Human-readable description for the IPSec policy.

transform_protocol plain xsd:string

The transform protocol. A valid value is ESP, AH, or AH-ESP. Default is ESP.

encapsulation_mode plain xsd:string

Encapsulation mode: tunnel(default), or transport.

auth_algorithm plain xsd:string

The authentication algorithm. A valid value is sha1, which is the default.

encryption_algorithm plain xsd:string

The encryption algorithm. A valid value is 3des, aes-128, aes-192, aes-256, and so on. Default is aes-128.

pfs plain xsd:string

Perfect forward secrecy (PFS). A valid value is Group2, Group5, Group14, and so on. Default is Group5.

lifetime plain xsd:dict

The lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime.

units plain xsd:string

Units for lifetime of the security association. Default is seconds.

value plain xsd:int

Lifetime value, as a positive integer. Default is 3600 seconds.

{
    "ipsecpolicies": [
        {
            "name": "ipsecpolicy1",
            "transform_protocol": "esp",
            "auth_algorithm": "sha1",
            "encapsulation_mode": "tunnel",
            "encryption_algorithm": "aes-128",
            "pfs": "group14",
            "tenant_id": "ccb81365fe36411a9011e90491fe1330",
            "lifetime": {
                "units": "seconds",
                "value": 3600
            },
            "id": "5291b189-fd84-46e5-84bd-78f40c05d69c",
            "description": ""
        }
    ]
}

This operation does not accept a request body.

POST
/v2.0/vpn/ipsecpolicies
Create IPSec policy

Creates an IPSec policy.

 

The IP security policy specifies the authentication and encryption algorithms and encapsulation mode to use for the established VPN connection.

Normal response codes
201
Error response codes
badRequest (400), unauthorized (401)
Request parameters
Parameter Style Type Description
name (Optional) plain xsd:string

Human-readable name for the IPSec policy. Does not have to be unique.

description (Optional) plain xsd:string

Human-readable description for the IPSec policy.

transform_protocol (Optional) plain xsd:string

The transform protocol. A valid value is ESP, AH, or AH-ESP. Default is ESP.

encapsulation_mode (Optional) plain xsd:string

The encapsulation mode. A valid value is tunnel or transport. Default is tunnel.

auth_algorithm (Optional) plain xsd:string

The authentication algorithm. A valid value is sha1, which is the default.

encryption_algorithm (Optional) plain xsd:string

The encryption algorithm. A valid value is 3des, aes-128, aes-192, aes-256, and so on. Default is aes-128.

pfs (Optional) plain xsd:string

Perfect forward secrecy (PFS). A valid value is Group2, Group5, Group14, and so on. Default is Group5.

lifetime (Optional) plain xsd:dict

The lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime.

units (Optional) plain xsd:string

Units for lifetime of the security association. Default is seconds.

value (Optional) plain xsd:int

Lifetime value, as a positive integer. Default is 3600 seconds.

tenant_id plain csapi:uuid

Owner of the IPSec policy. Only administrative users can specify a tenant ID other than their own.

Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the IPSec policy.

tenant_id plain csapi:uuid

Owner of the VPN service. Only administrative users can specify a tenant ID other than their own.

name plain xsd:string

Human-readable name for the IPSec policy. Does not have to be unique.

description plain xsd:string

Human-readable description for the IPSec policy.

transform_protocol plain xsd:string

The transform protocol. A valid value is ESP, AH, or AH-ESP. Default is ESP.

encapsulation_mode plain xsd:string

Encapsulation mode: tunnel(default), or transport.

auth_algorithm plain xsd:string

The authentication algorithm. A valid value is sha1, which is the default.

encryption_algorithm plain xsd:string

The encryption algorithm. A valid value is 3des, aes-128, aes-192, aes-256, and so on. Default is aes-128.

pfs plain xsd:string

Perfect forward secrecy (PFS). A valid value is Group2, Group5, Group14, and so on. Default is Group5.

lifetime plain xsd:dict

The lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime.

units plain xsd:string

Units for lifetime of the security association. Default is seconds.

value plain xsd:int

Lifetime value, as a positive integer. Default is 3600 seconds.

{
    "ipsecpolicy": {
        "name": "ipsecpolicy1",
        "transform_protocol": "esp",
        "auth_algorithm": "sha1",
        "encapsulation_mode": "tunnel",
        "encryption_algorithm": "aes-128",
        "pfs": "group5",
        "lifetime": {
            "units": "seconds",
            "value": 7200
        }
    }
}
{
    "ipsecpolicy": {
        "name": "ipsecpolicy1",
        "transform_protocol": "esp",
        "auth_algorithm": "sha1",
        "encapsulation_mode": "tunnel",
        "encryption_algorithm": "aes-128",
        "pfs": "group5",
        "tenant_id": "ccb81365fe36411a9011e90491fe1330",
        "lifetime": {
            "units": "seconds",
            "value": 7200
        },
        "id": "5291b189-fd84-46e5-84bd-78f40c05d69c",
        "description": ""
    }
}
GET
/v2.0/vpn/ipsecpolicies/​{ipsecpolicy_id}​
Show IPSec policy

Shows details for a specified IPSec policy.

 

Shows details for a specified IPSec policy.

Normal response codes
200
Error response codes
unauthorized (401), forbidden (403), itemNotFound (404)
Request parameters
Parameter Style Type Description
ipsecpolicy_id URI csapi:UUID The UUID for the IPSec policy.
Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the IPSec policy.

tenant_id plain csapi:uuid

Owner of the VPN service. Only administrative users can specify a tenant ID other than their own.

name plain xsd:string

Human-readable name for the IPSec policy. Does not have to be unique.

description plain xsd:string

Human-readable description for the IPSec policy.

transform_protocol plain xsd:string

The transform protocol. A valid value is ESP, AH, or AH-ESP. Default is ESP.

encapsulation_mode plain xsd:string

Encapsulation mode: tunnel(default), or transport.

auth_algorithm plain xsd:string

The authentication algorithm. A valid value is sha1, which is the default.

encryption_algorithm plain xsd:string

The encryption algorithm. A valid value is 3des, aes-128, aes-192, aes-256, and so on. Default is aes-128.

pfs plain xsd:string

Perfect forward secrecy (PFS). A valid value is Group2, Group5, Group14, and so on. Default is Group5.

lifetime plain xsd:dict

The lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime.

units plain xsd:string

Units for lifetime of the security association. Default is seconds.

value plain xsd:int

Lifetime value, as a positive integer. Default is 3600 seconds.

{
    "ipsecpolicy": {
        "name": "ipsecpolicy1",
        "transform_protocol": "esp",
        "auth_algorithm": "sha1",
        "encapsulation_mode": "tunnel",
        "encryption_algorithm": "aes-128",
        "pfs": "group14",
        "tenant_id": "ccb81365fe36411a9011e90491fe1330",
        "lifetime": {
            "units": "seconds",
            "value": 3600
        },
        "id": "5291b189-fd84-46e5-84bd-78f40c05d69c",
        "description": ""
    }
}

This operation does not accept a request body.

PUT
/v2.0/vpn/ipsecpolicies/​{ipsecpolicy_id}​
Update IPSec policy

Updates policy settings in a specified IPSec policy.

 
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
ipsecpolicy_id URI csapi:UUID The UUID for the IPSec policy.
name (Optional) plain xsd:string

Human-readable name for the IPSec policy. Does not have to be unique.

description (Optional) plain xsd:string

Human-readable description for the IPSec policy.

transform_protocol (Optional) plain xsd:string

The transform protocol. A valid value is ESP, AH, or AH-ESP. Default is ESP.

encapsulation_mode (Optional) plain xsd:string

The encapsulation mode. A valid value is tunnel or transport. Default is tunnel.

auth_algorithm (Optional) plain xsd:string

The authentication algorithm. A valid value is sha1, which is the default.

encryption_algorithm (Optional) plain xsd:string

The encryption algorithm. A valid value is 3des, aes-128, aes-192, aes-256, and so on. Default is aes-128.

pfs (Optional) plain xsd:string

Perfect forward secrecy (PFS). A valid value is Group2, Group5, Group14, and so on. Default is Group5.

lifetime (Optional) plain xsd:dict

The lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime.

units (Optional) plain xsd:string

Units for lifetime of the security association. Default is seconds.

value (Optional) plain xsd:int

Lifetime value, as a positive integer. Default is 3600 seconds.

Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the IPSec policy.

tenant_id plain csapi:uuid

Owner of the VPN service. Only administrative users can specify a tenant ID other than their own.

name plain xsd:string

Human-readable name for the IPSec policy. Does not have to be unique.

description plain xsd:string

Human-readable description for the IPSec policy.

transform_protocol plain xsd:string

The transform protocol. A valid value is ESP, AH, or AH-ESP. Default is ESP.

encapsulation_mode plain xsd:string

Encapsulation mode: tunnel(default), or transport.

auth_algorithm plain xsd:string

The authentication algorithm. A valid value is sha1, which is the default.

encryption_algorithm plain xsd:string

The encryption algorithm. A valid value is 3des, aes-128, aes-192, aes-256, and so on. Default is aes-128.

pfs plain xsd:string

Perfect forward secrecy (PFS). A valid value is Group2, Group5, Group14, and so on. Default is Group5.

lifetime plain xsd:dict

The lifetime of the security association. The lifetime consists of a unit and integer value. You can omit either the unit or value portion of the lifetime.

units plain xsd:string

Units for lifetime of the security association. Default is seconds.

value plain xsd:int

Lifetime value, as a positive integer. Default is 3600 seconds.

{
    "ipsecpolicy": {
        "pfs": "group14"
    }
}
{
    "ipsecpolicy": {
        "name": "ipsecpolicy1",
        "transform_protocol": "esp",
        "auth_algorithm": "sha1",
        "encapsulation_mode": "tunnel",
        "encryption_algorithm": "aes-128",
        "pfs": "group14",
        "tenant_id": "ccb81365fe36411a9011e90491fe1330",
        "lifetime": {
            "units": "seconds",
            "value": 3600
        },
        "id": "5291b189-fd84-46e5-84bd-78f40c05d69c",
        "description": ""
    }
}
DELETE
/v2.0/vpn/ipsecpolicies/​{ipsecpolicy_id}​
Remove IPSec policy

Removes a specified IPSec policy.

 

Removes the IPSec policy specified in the request.

Normal response codes
204
Error response codes
unauthorized (401), itemNotFound (404), conflict (409)
Request parameters
Parameter Style Type Description
ipsecpolicy_id URI csapi:UUID The UUID for the IPSec policy.

This operation does not accept a request body and does not return a response body.

GET
/v2.0/vpn/ipsecsiteconnections
List IPSec connections

Lists IPSec connections.

 
Normal response codes
200
Error response codes
unauthorized (401), forbidden (403)
Response parameters
Parameter Style Type Description
ipsec_site_connections plain xsd:list

IPSec site-to-site connection objects.

id plain csapi:uuid

The unique ID for the IPSec connection.

tenant_id plain csapi:uuid

Owner of the IPSec connection. Only administrative users can specify a tenant ID other than their own.

name plain xsd:string

Human-readable name for the IPSec connection. Does not have to be unique.

description plain xsd:string

Human-readable description for the IPSec connection.

peer_address plain xsd:string

Peer gateway public IPv4/IPv6 address or FQDN.

peer_id plain xsd:string

Peer router identity for authentication. Can be IPv4/IPv6 address, e-mail address, key id, or FQDN. Typically is same as peer_address.

peer_cidrs plain xsd:list

Unique list of valid peer private CIDRs in the form <net_address>/<prefix>.

route_mode plain xsd:string

The route mode. A valid value is static, which is the default.

mtu plain xsd:int

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

auth_mode plain xsd:string

The authentication mode. A valid value is psk, which is the default.

psk plain xsd:string

Pre Shared Key: any string

initiator plain xsd:string

Indicates whether this VPN can only respond to connections or both respond to and initiate connections. A valid value is response-only or bi-directional. Default is bi-directional.

admin_state_up plain xsd:boolean

The administrative state of the IPSec connection, which is up (true) or down (false). If down, the connection does not forward packets.

status plain xsd:string

Indicates whether the IPSec connection is currently operational. Possible values include: ACTIVE, DOWN, BUILD, ERROR, PENDING_CREATE, PENDING_UPDATE, or PENDING_DELETE.

ikepolicy_id plain csapi:uuid

Unique identifier of IKE policy.

ipsecpolicy_id plain csapi:uuid

Unique identifier of IPSec policy.

vpnservice_id plain csapi:uuid

Unique identifier of VPN service.

dpd plain xsd:dict

Dictionary with Dead Peer Detection protocol controls.

action plain xsd:string

The DPD action. A valid value is clear, hold, restart, disabled, or restart-by-peer. Default value is hold.

interval plain xsd:int

The DPD interval, in seconds. A valid value is a positive integer. Default is 30.

timeout plain xsd:int

The DPD timeout, in seconds. A valid value is a positive integer that is greater than the DPD interval value. Default is 120.

{
    "ipsec_site_connections": [
        {
            "status": "PENDING_CREATE",
            "psk": "secret",
            "initiator": "bi-directional",
            "name": "vpnconnection1",
            "admin_state_up": true,
            "tenant_id": "ccb81365fe36411a9011e90491fe1330",
            "description": "",
            "auth_mode": "psk",
            "peer_cidrs": [
                "10.1.0.0/24"
            ],
            "mtu": 1500,
            "ikepolicy_id": "bf5612ac-15fb-460c-9b3d-6453da2fafa2",
            "dpd": {
                "action": "hold",
                "interval": 30,
                "timeout": 120
            },
            "route_mode": "static",
            "vpnservice_id": "c2f3178d-5530-4c4a-89fc-050ecd552636",
            "peer_address": "172.24.4.226",
            "peer_id": "172.24.4.226",
            "id": "cbc152a0-7e93-4f98-9f04-b085a4bf2511",
            "ipsecpolicy_id": "8ba867b2-67eb-4835-bb61-c226804a1584"
        }
    ]
}

This operation does not accept a request body.

POST
/v2.0/vpn/ipsecsiteconnections
Create IPSec connection

Creates an IPSec connection.

 

Creates a site-to-site IPSec connection for a service.

Normal response codes
201
Error response codes
badRequest (400), unauthorized (401)
Request parameters
Parameter Style Type Description
name (Optional) plain xsd:string

Human-readable name for the IPSec connection. Does not have to be unique.

description (Optional) plain xsd:string

Human-readable description for the IPSec connection.

peer_address plain xsd:string

Peer gateway public IPv4/IPv6 address or FQDN.

peer_id plain xsd:string

Peer router identity for authentication. Can be IPv4/IPv6 address, e-mail address, key id, or FQDN. Typically is same as peer_address.

peer_cidrs plain xsd:list

Unique list of valid peer private CIDRs in the form <net_address>/<prefix>.

mtu (Optional) plain xsd:int

Maximum Transmission Unit to address fragmentation. Minimum is 68 for IPv4, and 1280 for IPv6.

psk plain xsd:string

The pre-shared key. A valid value is any string.

initiator (Optional) plain xsd:string

Indicates whether this VPN can only respond to connections or both respond to and initiate connections. A valid value is response-only or bi-directional. Default is bi-directional.

admin_state_up (Optional) plain xsd:boolean

The administrative state of the IPSec connection, which is up (true) or down (false). If down, the connection does not forward packets.

dpd (Optional) plain xsd:dict

Dictionary with dead peer detection (DPD) protocol controls.

action (Optional) plain xsd:string

The DPD action. A valid value is clear, hold, restart, disabled, or restart-by-peer. Default value is hold.

interval (Optional) plain xsd:int

The DPD interval, in seconds. A valid value is a positive integer. Default is 30.

timeout (Optional) plain xsd:int

The DPD timeout in seconds. A valid value is a positive integer that is greater than the DPD interval value. Default is 120.

tenant_id plain csapi:uuid

Owner of the IPSec connection. Only administrative users can specify a tenant ID other than their own.

route_mode (Optional) plain xsd:string

The route mode. A valid value is static, which is the default.

auth_mode (Optional) plain xsd:string

The authentication mode. A valid value is psk, which is the default.

status (Optional) plain xsd:string

The operational status of the IPSec connection. A possible value is ACTIVE, DOWN, BUILD, ERROR, PENDING_CREATE, PENDING_UPDATE, or PENDING_DELETE.

ikepolicy_id plain csapi:uuid

Unique identifier of IKE policy.

ipsecpolicy_id plain csapi:uuid

Unique identifier of IPSec policy.

vpnservice_id plain csapi:uuid

Unique identifier of VPN service.

Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the IPSec connection.

tenant_id plain csapi:uuid

Owner of the IPSec connection. Only administrative users can specify a tenant ID other than their own.

name plain xsd:string

Human-readable name for the IPSec connection. Does not have to be unique.

description plain xsd:string

Human-readable description for the IPSec connection.

peer_address plain xsd:string

Peer gateway public IPv4/IPv6 address or FQDN.

peer_id plain xsd:string

Peer router identity for authentication. Can be IPv4/IPv6 address, e-mail address, key id, or FQDN. Typically is same as peer_address.

peer_cidrs plain xsd:list

Unique list of valid peer private CIDRs in the form <net_address>/<prefix>.

route_mode plain xsd:string

The route mode. A valid value is static, which is the default.

mtu plain xsd:int

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

auth_mode plain xsd:string

The authentication mode. A valid value is psk, which is the default.

psk plain xsd:string

Pre Shared Key: any string

initiator plain xsd:string

Indicates whether this VPN can only respond to connections or both respond to and initiate connections. A valid value is response-only or bi-directional. Default is bi-directional.

admin_state_up plain xsd:boolean

The administrative state of the IPSec connection, which is up (true) or down (false). If down, the connection does not forward packets.

status plain xsd:string

Indicates whether the IPSec connection is currently operational. Possible values include: ACTIVE, DOWN, BUILD, ERROR, PENDING_CREATE, PENDING_UPDATE, or PENDING_DELETE.

ikepolicy_id plain csapi:uuid

Unique identifier of IKE policy.

ipsecpolicy_id plain csapi:uuid

Unique identifier of IPSec policy.

vpnservice_id plain csapi:uuid

Unique identifier of VPN service.

dpd plain xsd:dict

Dictionary with Dead Peer Detection protocol controls.

action plain xsd:string

The DPD action. A valid value is clear, hold, restart, disabled, or restart-by-peer. Default value is hold.

interval plain xsd:int

The DPD interval, in seconds. A valid value is a positive integer. Default is 30.

timeout plain xsd:int

The DPD timeout, in seconds. A valid value is a positive integer that is greater than the DPD interval value. Default is 120.

{
    "ipsec_site_connection": {
        "psk": "secret",
        "initiator": "bi-directional",
        "ipsecpolicy_id": "22b8abdc-e822-45b3-90dd-f2c8512acfa5",
        "admin_state_up": true,
        "peer_cidrs": [
            "10.2.0.0/24"
        ],
        "mtu": "1500",
        "ikepolicy_id": "d3f373dc-0708-4224-b6f8-676adf27dab8",
        "dpd": {
            "action": "disabled",
            "interval": 60,
            "timeout": 240
        },
        "vpnservice_id": "7b347d20-6fa3-4e22-b744-c49ee235ae4f",
        "peer_address": "172.24.4.233",
        "peer_id": "172.24.4.233",
        "name": "vpnconnection1"
    }
}
{
    "ipsec_site_connection": {
        "status": "PENDING_CREATE",
        "psk": "secret",
        "initiator": "bi-directional",
        "name": "vpnconnection1",
        "admin_state_up": true,
        "tenant_id": "b6887d0b45b54a249b2ce3dee01caa47",
        "description": "",
        "auth_mode": "psk",
        "peer_cidrs": [
            "10.2.0.0/24"
        ],
        "mtu": 1500,
        "ikepolicy_id": "d3f373dc-0708-4224-b6f8-676adf27dab8",
        "dpd": {
            "action": "disabled",
            "interval": 60,
            "timeout": 240
        },
        "route_mode": "static",
        "vpnservice_id": "7b347d20-6fa3-4e22-b744-c49ee235ae4f",
        "peer_address": "172.24.4.233",
        "peer_id": "172.24.4.233",
        "id": "af44dfd7-cf91-4451-be57-cd4fdd96b5dc",
        "ipsecpolicy_id": "22b8abdc-e822-45b3-90dd-f2c8512acfa5"
    }
}
GET
/v2.0/vpn/ipsecsiteconnections/​{connection_id}​
Show IPSec connection

Shows details for a specified IPSec connection.

 
Normal response codes
200
Error response codes
unauthorized (401), forbidden (403), itemNotFound (404)
Request parameters
Parameter Style Type Description
connection_id URI csapi:UUID The UUID for the IPSec site-to-site connection.
Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the IPSec connection.

tenant_id plain csapi:uuid

Owner of the IPSec connection. Only administrative users can specify a tenant ID other than their own.

name plain xsd:string

Human-readable name for the IPSec connection. Does not have to be unique.

description plain xsd:string

Human-readable description for the IPSec connection.

peer_address plain xsd:string

Peer gateway public IPv4/IPv6 address or FQDN.

peer_id plain xsd:string

Peer router identity for authentication. Can be IPv4/IPv6 address, e-mail address, key id, or FQDN. Typically is same as peer_address.

peer_cidrs plain xsd:list

Unique list of valid peer private CIDRs in the form <net_address>/<prefix>.

route_mode plain xsd:string

The route mode. A valid value is static, which is the default.

mtu plain xsd:int

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

auth_mode plain xsd:string

The authentication mode. A valid value is psk, which is the default.

psk plain xsd:string

Pre Shared Key: any string

initiator plain xsd:string

Indicates whether this VPN can only respond to connections or both respond to and initiate connections. A valid value is response-only or bi-directional. Default is bi-directional.

admin_state_up plain xsd:boolean

The administrative state of the IPSec connection, which is up (true) or down (false). If down, the connection does not forward packets.

status plain xsd:string

Indicates whether the IPSec connection is currently operational. Possible values include: ACTIVE, DOWN, BUILD, ERROR, PENDING_CREATE, PENDING_UPDATE, or PENDING_DELETE.

ikepolicy_id plain csapi:uuid

Unique identifier of IKE policy.

ipsecpolicy_id plain csapi:uuid

Unique identifier of IPSec policy.

vpnservice_id plain csapi:uuid

Unique identifier of VPN service.

dpd plain xsd:dict

Dictionary with Dead Peer Detection protocol controls.

action plain xsd:string

The DPD action. A valid value is clear, hold, restart, disabled, or restart-by-peer. Default value is hold.

interval plain xsd:int

The DPD interval, in seconds. A valid value is a positive integer. Default is 30.

timeout plain xsd:int

The DPD timeout, in seconds. A valid value is a positive integer that is greater than the DPD interval value. Default is 120.

{
    "ipsec_site_connection": {
        "status": "PENDING_CREATE",
        "psk": "secret",
        "initiator": "bi-directional",
        "name": "vpnconnection1",
        "admin_state_up": true,
        "tenant_id": "ccb81365fe36411a9011e90491fe1330",
        "description": "",
        "auth_mode": "psk",
        "peer_cidrs": [
            "10.1.0.0/24"
        ],
        "mtu": 1500,
        "ikepolicy_id": "bf5612ac-15fb-460c-9b3d-6453da2fafa2",
        "dpd": {
            "action": "hold",
            "interval": 30,
            "timeout": 120
        },
        "route_mode": "static",
        "vpnservice_id": "c2f3178d-5530-4c4a-89fc-050ecd552636",
        "peer_address": "172.24.4.226",
        "peer_id": "172.24.4.226",
        "id": "cbc152a0-7e93-4f98-9f04-b085a4bf2511",
        "ipsecpolicy_id": "8ba867b2-67eb-4835-bb61-c226804a1584"
    }
}

This operation does not accept a request body.

PUT
/v2.0/vpn/ipsecsiteconnections/​{connection_id}​
Update IPSec connection

Updates connection settings for a specified IPSec connection.

 
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
connection_id URI csapi:UUID The UUID for the IPSec site-to-site connection.
name (Optional) plain xsd:string

Human-readable name for the IPSec connection. Does not have to be unique.

description (Optional) plain xsd:string

Human-readable description for the IPSec connection.

peer_address plain xsd:string

Peer gateway public IPv4/IPv6 address or FQDN.

peer_id plain xsd:string

Peer router identity for authentication. Can be IPv4/IPv6 address, e-mail address, key id, or FQDN. Typically is same as peer_address.

peer_cidrs plain xsd:list

Unique list of valid peer private CIDRs in the form <net_address>/<prefix>.

mtu (Optional) plain xsd:int

Maximum Transmission Unit to address fragmentation. Minimum is 68 for IPv4, and 1280 for IPv6.

psk plain xsd:string

The pre-shared key. A valid value is any string.

initiator (Optional) plain xsd:string

Indicates whether this VPN can only respond to connections or both respond to and initiate connections. A valid value is response-only or bi-directional. Default is bi-directional.

admin_state_up (Optional) plain xsd:boolean

The administrative state of the IPSec connection, which is up (true) or down (false). If down, the connection does not forward packets.

dpd (Optional) plain xsd:dict

Dictionary with dead peer detection (DPD) protocol controls.

action (Optional) plain xsd:string

The DPD action. A valid value is clear, hold, restart, disabled, or restart-by-peer. Default value is hold.

interval (Optional) plain xsd:int

The DPD interval, in seconds. A valid value is a positive integer. Default is 30.

timeout (Optional) plain xsd:int

The DPD timeout in seconds. A valid value is a positive integer that is greater than the DPD interval value. Default is 120.

Response parameters
Parameter Style Type Description
id plain csapi:uuid

The unique ID for the IPSec connection.

tenant_id plain csapi:uuid

Owner of the IPSec connection. Only administrative users can specify a tenant ID other than their own.

name plain xsd:string

Human-readable name for the IPSec connection. Does not have to be unique.

description plain xsd:string

Human-readable description for the IPSec connection.

peer_address plain xsd:string

Peer gateway public IPv4/IPv6 address or FQDN.

peer_id plain xsd:string

Peer router identity for authentication. Can be IPv4/IPv6 address, e-mail address, key id, or FQDN. Typically is same as peer_address.

peer_cidrs plain xsd:list

Unique list of valid peer private CIDRs in the form <net_address>/<prefix>.

route_mode plain xsd:string

The route mode. A valid value is static, which is the default.

mtu plain xsd:int

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

auth_mode plain xsd:string

The authentication mode. A valid value is psk, which is the default.

psk plain xsd:string

Pre Shared Key: any string

initiator plain xsd:string

Indicates whether this VPN can only respond to connections or both respond to and initiate connections. A valid value is response-only or bi-directional. Default is bi-directional.

admin_state_up plain xsd:boolean

The administrative state of the IPSec connection, which is up (true) or down (false). If down, the connection does not forward packets.

status plain xsd:string

Indicates whether the IPSec connection is currently operational. Possible values include: ACTIVE, DOWN, BUILD, ERROR, PENDING_CREATE, PENDING_UPDATE, or PENDING_DELETE.

ikepolicy_id plain csapi:uuid

Unique identifier of IKE policy.

ipsecpolicy_id plain csapi:uuid

Unique identifier of IPSec policy.

vpnservice_id plain csapi:uuid

Unique identifier of VPN service.

dpd plain xsd:dict

Dictionary with Dead Peer Detection protocol controls.

action plain xsd:string

The DPD action. A valid value is clear, hold, restart, disabled, or restart-by-peer. Default value is hold.

interval plain xsd:int

The DPD interval, in seconds. A valid value is a positive integer. Default is 30.

timeout plain xsd:int

The DPD timeout, in seconds. A valid value is a positive integer that is greater than the DPD interval value. Default is 120.

{
    "ipsec_site_connection": {
        "mtu": "2000"
    }
}
{
    "ipsec_site_connection": {
        "status": "DOWN",
        "psk": "secret",
        "initiator": "bi-directional",
        "name": "vpnconnection1",
        "admin_state_up": true,
        "tenant_id": "26de9cd6cae94c8cb9f79d660d628e1f",
        "description": "",
        "auth_mode": "psk",
        "peer_cidrs": [
            "10.2.0.0/24"
        ],
        "mtu": 2000,
        "ikepolicy_id": "771f081c-5ec8-4f9a-b041-015dfb7fbbe2",
        "dpd": {
            "action": "hold",
            "interval": 30,
            "timeout": 120
        },
        "route_mode": "static",
        "vpnservice_id": "41bfef97-af4e-4f6b-a5d3-4678859d2485",
        "peer_address": "172.24.4.233",
        "peer_id": "172.24.4.233",
        "id": "f7cf7305-f491-45f4-ad9c-8e7240fe3d72",
        "ipsecpolicy_id": "9958d4fe-3719-4e8c-84e7-9893895b76b4"
    }
}
DELETE
/v2.0/vpn/ipsecsiteconnections/​{connection_id}​
Remove IPSec connection

Removes a specified IPSec connection.

 

Removes the IPSec connection specified in the request.

Normal response codes
204
Error response codes
unauthorized (401), itemNotFound (404), conflict (409)
Request parameters
Parameter Style Type Description
connection_id URI csapi:UUID The UUID for the IPSec site-to-site connection.

This operation does not accept a request body and does not return a response body.

Extra routes

Adds extra routes to the router resource.

You can update a router to add a set of nexthop IPs and destination CIDRs.

The nexthop IP must be a part of a subnet to which the router interfaces are connected. You can configure the routes attribute on only update operations.

PUT
/v2.0/routers/​{router_id}​
Update router

Configures extra routes on a specified router.

 

The next hop IP address must be a part of one of the subnets to which the router interfaces are connected. Otherwise, the server responds with the 400 Bad Request error code.

When a validation error is detected, such as a format error of IP address or CIDR, the server responds with the 400 Bad Request error code.

When Networking receives a request to delete the router interface for subnets that are used by one or more routes, it responds with a 409 Conflict error code.

Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), itemNotFound (404), conflict (409)
Request parameters
Parameter Style Type Description
router_id URI csapi:UUID The UUID for the router of interest to you.
routes (Optional) plain xsd:dict

List of dictionary pairs in this format:

[
  {
    "nexthop":"IPADDRESS",
    "destination":"CIDR"
  }
]
next_hop (Optional) plain xsd:string

The IP address of the next hop.

destination (Optional) plain xsd:string

The destination CIDR.

{
    "router": {
        "routes": [
            {
                "nexthop": "10.1.0.10",
                "destination": "40.0.1.0/24"
            }
        ]
    }
}
{
    "router": {
        "status": "ACTIVE",
        "external_gateway_info": {
            "network_id": "5c26e0bb-a9a9-429c-9703-5c417a221096",
            "external_fixed_ips": [
                {
                    "subnet_id": "255.255.255.0",
                    "ip": "192.168.10.2"
                }
            ]
        },
        "name": "router1",
        "admin_state_up": true,
        "tenant_id": "936fa220b2c24a87af51026439af7a3e",
        "routes": [
            {
                "nexthop": "10.1.0.10",
                "destination": "40.0.1.0/24"
            }
        ],
        "id": "babc8173-46f6-4b6f-8b95-38c1683a4e22"
    }
}