A Cyclades network is a virtual network that can be, depending on it’s Network Flavor, either an isolated Layer-2 broadcast domain or a Layer-3 network. Networks can either be private or public. Private networks are reserved for the user who created it, while public networks are created by the administrator and are visible to all users. Also, networks can be marked with the –router:external attribute to indicate that are external networks (public internet)
Currently there are four available Networks Flavors:
The administrator can limit which networks can be created via API with the API_ENABLED_NETOWRK_FLAVORS setting.
The attributes for network objects are the following:
Note: The ‘admin_state_up’ value is used only for compatibility with Neutron API. It will be read-only, and will always be True.
Method: POST
URI: /networks
The body of the request must contain the ‘type’ of the network. Also it can contain a ‘name’ attribute.
METHOD: GET
URI: /networks/$(network_id)
Example response:
| Field | Value |
|---|---|
| admin_state_up | True |
| id | 42 |
| name | Test_network |
| network_type | MAC_FILTERED |
| router:external | False |
| public | False |
| status | ACTIVE |
| subnets | [] |
| SNF:floating_ip | False |
| user_id | 1012fd8c72284c00b133832cd179f896 |
| tenant_id | 1012fd8c72284c00b133832cd179f896 |
METHOD: DELETE
URI: /networks/$(network_id)
The network cannot be deleted if there are any Ports connected to it or any FloatingIPs reserved from this network. The subnets that are connected to this network are automatically deleted upon network deletion.
METHOD: PUT
URI: /networks/$(network_id)
Only the name of the network can be updated.
A subnet represents L3-Layer characteristics of the network that is associated with. Specifically, it represents an IP address block that is used in order to assign addresses to virtual machines. A subnet is associated with a network when created.
The attributes for subnet objects are the following:
Note: ‘host_routes’ and ‘dns_nameservers’ is used only for compatibility with Neutron. These values will be read-only and always be [].
METHOD: POST
URI: /subnets/
To create a subnet the user must specify the network_id and the cidr for the subnet. If the CIDR is an IPv6 subnet, the user must set the ip_version to 6. If allocation pools overlap, or gateway overlaps with allocation_pools then 409 conflict is returned.
Finally, the user can create maximum one subnet of each ip_version, meaning that a network can have no subnets, or one IPv4 subnet or one IPv6 subnet, or one IPv4 and one IPv6 subnet. Also the user cannot create a subnet for a network that has or had a port connected to it.
Note: Bulk creation of subnets, is not supported.
METHOD: GET
URI: /subnets/$(subnet_id)
Example response:
| Field | Value |
|---|---|
| allocation_pools | {“start”: “192.168.2.2”, “end”: “192.168.2.254”} |
| cidr | 192.168.2.0/24 |
| dns_nameservers | [] |
| enable_dhcp | False |
| gateway_ip | 192.168.2.1 |
| host_routes | [] |
| id | 49ce3872-446c-43e9-aa22-68dbc2bac0b5 |
| ip_version | 4 |
| name | test1 |
| network_id | 8fc5e2bf-9c1b-4458-8f71-e38177ed23a5 |
| tenant_id | 11a65261147d462b998eafb7f696f0ba |
| user_id | 11a65261147d462b998eafb7f696f0ba |
METHOD: DELETE
URI: /subnets/$(subnet_id)
We do not allow deletion of subnets. Subnets will be deleted when the network is deleted. This call will return 400 (badRequest).
METHOD: PUT
URI: /subnets/$(subnet_id)
Only the name of the subnet can be updated. This call will return 400 (badRequest) if the user tries to update any other field.
A port represents a virtual switch port on a network switch. Virtual machines attach their interfaces to ports. A port that is connected to a network gets an IP address for each subnet that is associated with the network. If the network has no subnets, then the port will have no IP.
The attributes for port objects are the following:
Note
Due to the way ports are implementing to Ganeti, a port will get an IPv6 address from a subnet only when the state of the port becomes ‘ACTIVE’.
Note
The ‘admin_state_up’ value is used only for compatibility with Neutron API. It will be read-only, and will always be True.
Method: POST
URI: /ports
The body of the request must contain the ‘network_id’ of the network that the port will be associated with. If the request contains a ‘device_Id’, the port will be connected to that device.
The new port will get an IPv4 address from each of the subnets that are associated with that network. If the network has an IPv4 subnet the request can also contain the ‘fixed_ips’ attribute containing a specific IPv4 address to use.
Creating a port to a public network is only supported if the user has a floating IP from this network (see /floatingips extension) and the ‘fixed_ip’ attribute of the request contains the IPv4 address of this floating IP. Otherwise, badRequest(400) is returned.
Finally, the request can contain the following optional attributes:
Example request:
METHOD: GET
URI: /ports/$(port_id)
Example response:
| Field | Value |
|---|---|
| admin_state_up | True |
| device_id | 39a02a66-33be-478a-8e9f-012141258678 |
| device_owner | network:router_interface |
| fixed_ips | {“subnet_id”: “2313705f-68c1-4e16-80e3-c9fd8c0a5170”, “ip_address”: “10.0.2.1”} |
| id | ff15e3fe-7b39-4adc-ae98-a7e29588977e |
| mac_address | fa:16:3e:c1:63:06 |
| name | “test_port” |
| network_id | 2f04b49f-ca49-4b93-9139-11a4eca35fdd |
| security_groups | [] |
| status | DOWN |
| tenant_id | 1012fd8c72284c00b133832cd179f896 |
| user_id | 1012fd8c72284c00b133832cd179f896 |
METHOD: DELETE
URI: /ports/$(port_id)
Deleting a port from a public network is only allowed if the port has been creating using a floating IP address.
Floating IPs are addresses on external networks (and so can be defined only on networks on which the attribute router:external has been set to True) that are marked as floating IP pools (SNF:floating_ip_pool). In the Neutron API, floating IPs are associated with specific ports and IP addresses on private networks and are used to allow an instance from a private network to access the external network. Cyclades are able to associate a floating IP with an instance without the restriction that the instance must already have a port and a private IP from a private network. In order to avoid this limitation of Neutron API, Cyclades are using a slightly modified and extended API.
The attributes of floating IP objects are the following:
Floating IPs can be used via the /ports API. In order to attach a floating IP to a server, the user must create a port that specified the IPv4 address of the floating IP in the fixed_ips attribute of the port creation request. Also, the floating IP can be detached from the server by destroying the port that the floating IP is attached to.
METHOD: POST
URI: /floatingips
The body of the request contains the id of the external network (floating_network_id). If no address is specified (floating_ip_address), an address will automatically be allocated from the pool addresses of the external network.
METHOD: GET
URI: /floatingips/$(floatingip_id)
Example response:
{
"floatingip": {
"id": "5923c02a-a162-4044-a432-9e52d6d819ce",
"floating_ip_address": 192.168.1.227,
"floating_network_id": 00983314-2f3c-43e9-acb0-9fd7cdb32231,
"router_id": null,
"device_id": 42,
"tenant_id: "1012fd8c72284c00b133832cd179f896",
"user_id": "1012fd8c72284c00b133832cd179f896"
}
}
METHOD: DELETE
URI: /floatingips/$(floatingip_id)
This operation removes(releases) the floating IP. If it associated with a device(port), the port is automatically removed.
Note
This section contains a draft design document for virtual routers, and currently there is no implementation for this API.
A router is a logical entity that can be used to:
A router is associated with subnets through interfaces. The router gets an interface with each subnet that is associated with. By default, the IP address of such interface is the gateway of the subnet. Besides the interfaces, the router also gets a Port for each network that is associated with (through the corresponding subnets). These ports are created automatically when interfaces are added to the router, have as device_owner the router, and can not be managed with the Port API.
Besides the internal subnets, the router, can also be associated with an external network in order to NAT traffic from internal networks to the external one. The id of the external network is specified in the external_gateway_info attribute of the network, and a port will be created for the router with an IP address from the range of the public network. Besides the network id, the user can also specify a floating IP from this network, to use as the router IP. This port can also not be managed with the Port API.
The attributes for Router objects are the following:
Method: POST
URI: /routers
The body of the request contains the name of the router. The new router that is created does not have any internal interface and so it is not associated with any subnet.
Also, the used can specify an external gateway for the router at create time. This is done by specifying the network_id in the external_gateway_info attribute. This network must have the attribute router:external set to True. Besides the id of the network, the used can also specify one of his floating IPs to use. An example request is the following
{
"router":
{
"name": "example_router",
"external_gateway_info":
{
"network_id": "42",
"floating_ip_id": "142"
}
}
}
METHOD: GET
URI: /routers/$(router_id)
Example response:
{
"id": "5",
"name": "example_router",
"status": "ACTIVE",
"user_id": "1012fd8c72284c00b133832cd179f896",
"tenant_id": "1012fd8c72284c00b133832cd179f896",
"external_gateway_info": {
"network_id": "42",
"floating_ip_id": "142"
}
}
METHOD: DELETE
URI: /routers/$(router_id)
This operation removes a logical router; the operation will fail if the router still has some internal interfaces.
METHOD: PUT
URI: /routers/$(router_id)
Only the name of the router and the external_gateway_info can be updated.
METHOD: PUT
URI: /routers/$(router_id)/add_router_interface
The body of the request contains only the id of the subnet that the router will be associated to.
METHOD: PUT
URI: /routers/$(router_id)/remove_router_interface
The body of the request contains only the id of the subnet that the router will be detached from.
Creation of a network corresponds to only creating a Network object in the Cyclades DB. Also, creation of a subnet corresponds to creation of a Subnet in the Cyclades DB and the of the corresponding allocation pools. The Ganeti network will only be created in the Ganeti backend when a port is connected to this network. Updating fields of Ganeti networks is really hard (e.g., changing the dhcp option) or impossible (e.g., changing the subnet). For this reason, if the network has been created in a Ganeti backend, then it will be marked as read-only!
A port is mapped to a Ganeti NIC directly. The port will be created in DB in the “BUILD” state and an OP_INSTANCE_MODIFY will be issued to Ganeti to create the NIC in the specified VM. When the job successfully completes, the NIC will be updated to state “ACTIVE” in the DB. Also the MAC address that was allocated from Ganeti will be stored in the updated NIC.