L3 Network¶
Table of contents
Overview¶
A L3 network is a logic network that contains a subnet and a set of network services, and that is built up on a L2 network that is responsible for providing isolation method. Network services, which are provided by network service providers associated with the underlying L2 network, are usually software that implement protocols spanning from OSI layer 3 to OSI layer 7.
Subnet¶
In a L3 network, the subnet can have a single consecutive IP range or multiple split IP ranges. The split IP ranges are typically useful when a portion of IP addresses needs to be reserved from the subnet. For example, let’s say you are going to create a L3 network as a management network that has a subnet 192.168.0.0/24; however, IP addresses of 192.168.0.50 ~ 192.168.0.100 have been occupied by some network devices and you don’t want ZStack to use them, then you can create two split IP ranges:
IP Range1
start IP: 192.168.0.2
end IP: 192.168.0.49
gateway: 192.168.0.1
netmask: 255.255.255.0
IP Range2
start IP: 192.168.0.101
end IP: 192.168.0.254
gateway: 192.168.0.1
netmask: 255.255.255.0
You can create split IP ranges as many as you want, as long as they all belong to the same CIDR.
Network Services¶
Network services implementing OSI layer 3 ~ layer 7 protocols aim to serve VMs on a L3 network. Network services are provided by network services providers that are associated to the parent L2 network of a L3 network. A type of network service can have multiple providers, and a provider can provide several types of different services. After a L3 network is created, users can attach network services to it and choose network services providers. In this ZStack version, a table of supported services/providers is shown as follows:
Network Service | Provider | Attachable L2 Network | Since |
---|---|---|---|
DHCP | Virtual Router |
|
0.6 |
DNS | Virtual Router |
|
0.6 |
Source NAT (SNAT) | Virtual Router |
|
0.6 |
Port Forwarding | Virtual Router |
|
0.6 |
Elastic IP (EIP) | Virtual Router |
|
0.6 |
Security Group | Security Group |
|
0.6 |
In the table, the column ‘Attachable L2 Network’ indicates what L2 networks providers can attach. If a provider cannot attach to a L2 network, it cannot provide services to child L3 networks of the L2 network.
Inventory¶
Properties¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
uuid | see Resource Properties | 0.6 | ||
name | see Resource Properties | 0.6 | ||
description | see Resource Properties | true | 0.6 | |
zoneUuid | uuid of ancestor zone, see zone | 0.6 | ||
l2NetworkUuid | uuid of parent L2 network, see L2 network | 0.6 | ||
state | see state |
|
0.6 | |
dnsDomain | see domain | true | 0.6 | |
ipRanges | a list of IP ranges | 0.6 | ||
dns | a list of DNS | 0.6 | ||
networkServices | a list of network services references | 0.6 | ||
type | L3 network type |
|
0.6 | |
createDate | see Resource Properties | 0.6 | ||
lastOpDate | see Resource Properties | 0.6 |
Example¶
{
"inventory": {
"uuid": "f73926eb4f234f8195c61c33d8db419d",
"name": "GuestNetwork",
"description": "Test",
"type": "L3BasicNetwork",
"zoneUuid": "732fbb4383b24b019f60d862995976bf",
"l2NetworkUuid": "f1a092c6914840c9895c564abbc55375",
"state": "Enabled",
"createDate": "Jun 1, 2015 11:07:24 PM",
"lastOpDate": "Jun 1, 2015 11:07:24 PM",
"dns": [],
"ipRanges": [
{
"uuid": "78b43f4b0a9745fab49c967e1c35beb1",
"l3NetworkUuid": "f73926eb4f234f8195c61c33d8db419d",
"name": "TestIpRange",
"description": "Test",
"startIp": "10.10.2.100",
"endIp": "10.20.2.200",
"netmask": "255.0.0.0",
"gateway": "10.10.2.1",
"createDate": "Jun 1, 2015 11:07:24 PM",
"lastOpDate": "Jun 1, 2015 11:07:24 PM"
}
],
"networkServices": [
{
"l3NetworkUuid": "f73926eb4f234f8195c61c33d8db419d",
"networkServiceProviderUuid": "bbb525dc4cc8451295d379797e092dba",
"networkServiceType": "DHCP"
}
]
}
}
State¶
L3 networks have two states:
Enabled
The state that allows new VMs to be created
Disabled
The state that DOESN’T allow new VMs to be created
Note
Existing VMs on disabled L3 networks can still be stopped, started, rebooted, and deleted.
DNS Domain¶
The DNS domain is used to expand hostnames of VMs on the L3 network to FQDNs(Full Qualified Domain Name); for example, if the hostname of a VM is ‘vm1’ and the DNS domain of the L3 network is ‘zstack.org’, the final hostname will be expanded to ‘vm1.zstack.org’.
IP Range¶
In this ZStack version, only IPv4 IP range is supported.
Inventory¶
Properties¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
uuid | see Resource Properties | 0.6 | ||
name | see Resource Properties | 0.6 | ||
description | see Resource Properties | true | 0.6 | |
startIp | the first IP in range | 0.6 | ||
endIp | the last IP in range | 0.6 | ||
netmask | netmask of subnet | 0.6 | ||
gateway | gateway of subnet | 0.6 | ||
createDate | see Resource Properties | 0.6 | ||
lastOpDate | see Resource Properties | 0.6 |
Example¶
{
"inventory": {
"uuid": "b1cfcdeca4024d13ac82edbe8d959720",
"l3NetworkUuid": "50e637dc68b7480291ba87cbb81d94ad",
"name": "TestIpRange",
"description": "Test",
"startIp": "10.0.0.100",
"endIp": "10.10.1.200",
"netmask": "255.0.0.0",
"gateway": "10.0.0.1",
"createDate": "Jun 1, 2015 4:30:23 PM",
"lastOpDate": "Jun 1, 2015 4:30:23 PM"
}
}
DNS¶
A L3 network can have one or more DNS that take effect when the DNS network service is enabled.
Note
In this ZStack version, only IPv4 DNS is supported
L2 Networks and L3 Networks¶
As a layer2 broadcast domain can contain multiple subnets, nothing will stop you from creating multiple L3 networks on the same L2 network; however, those L3 networks are not isolated and network snooping can happen; please use on your own risks.
Network Service References¶
Network service references exhibit network services enabled on the L3 network and their providers.
Inventory¶
Properties¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
l3NetworkUuid | L3 network Uuid | 0.6 | ||
networkServiceProviderUuid | network service provider UUID | 0.6 | ||
networkServiceType | network service type |
|
0.6 |
Network Typology¶
The most common network typologies in IaaS software managed clouds are:
Flat Network or Shared Network:
In this typology, all tenants share a single subnet; IaaS software only provides DHCP, DNS services; the router of datacenter is responsible for routing
Private Network or Isolated Network:
In this typology, each tenant has own subnet; IaaS software is responsible for providing routers for all subnets, which usually have DHCP, DNS, and NAT services.
Virtual Private Network (VPC):
In this typology, each tenant can have multiple subnets; IaaS software is responsible for providing a router coordinating all subnets; tenants can configure the routing table of the router to control connectivity amid subnets.
Besides, typical typologies can be combined to new typologies; for example, a flat network and a private network can be put together, as:
In ZStack, all those typologies can be implemented by assembling L2 networks, L3 networks and network services. For example, to create a flat network, users can create a L3 network with only DHCP, DNS enabled; to create a private network, users can create a L3 network on a L2VlanNetwork with DHCP, DNS, SNAT enabled.
Note
In this ZStack version, VPC is not supported yet.
Operations¶
Create L3 Network¶
Users can use CreateL3Network to create a L3 network. For example:
CreateL3Network l2NetworkUuid=f1a092c6914840c9895c564abbc55375 name=GuestNetwork
Parameters¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
name | resource name, see Resource Properties | 0.6 | ||
resourceUuid | resource uuid, see Create Resources | true | 0.6 | |
description | resource description, see Resource Properties | true | 0.6 | |
l2NetworkUuid | uuid of parent L2 network, see L2 network | 0.6 | ||
dnsDomain | a DNS domain, see domain | true | 0.6 | |
type | L3 network type, see type | true |
|
0.6 |
system | indicates whether this is a system L3 network, see System L3 Network | true |
|
0.6 |
Type¶
In this ZStack version, the only L3 network type is L3BasicNetwork. Users can leave field ‘type’ alone when calling CreateL3Network.
System L3 Network¶
A system L3 network is reserved for ZStack and cannot be used to create user VMs. System L3 networks are typically used for public networks and management networks. Usually, user VMs in a cloud should not have nics on a public network and a management network, but appliance VMs (e.g router VM) do need have nics on those networks; then the management network and the public network can be created as system L3 networks.
Note
Management networks and public networks can also be created as non-system L3 networks, which allows user VMs to use them. This is normally seen in private clouds; for example, creating a user VM with a public IP directly.
Delete L3 Network¶
Users can use DeleteL3Network to delete a L3 network. For example:
DeleteL3Network uuid=f73926eb4f234f8195c61c33d8db419d
Parameters¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
uuid | L3 network uuid | 0.6 | ||
deleteMode | see Delete Resources | true |
|
0.6 |
Danger
Deleting a L3 network will stop all VMs that have nics on it and will delete the nics from VMs; if the nic on the L3 network is the only nic of a VM, the VM will be deleted as well. There is no way to recover a deleted L3 network.
Add IP Ranges¶
Add Split Ranges¶
Users can use AddIpRange to add an IP range to a L3 network; this is useful for adding split IP ranges. For example:
AddIpRange name=ipr1 startIp=192.168.0.2 endIp=192.168.0.100 netmask=255.255.255.0 gateway=192.168.0.1 resourceUuid=50e637dc68b7480291ba87cbb81d94ad
Parameters¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
name | resource name, see Resource Properties | 0.6 | ||
resourceUuid | resource uuid, see Create Resources | true | 0.6 | |
description | resource description, see Resource Properties | true | 0.6 | |
l3NetworkUuid | uuid of parent L3 network | 0.6 | ||
startIp | the first IP in range | 0.6 | ||
endIp | the last IP in range | 0.6 | ||
netmask | netmask of subnet | 0.6 | ||
gateway | gateway of subnet | 0.6 |
Add CIDR¶
Users can also use AddIpRangeByNetworkCidr to add an IP range. For example:
AddIpRangeByNetworkCidr name=ipr1 l3NetworkUuid=50e637dc68b7480291ba87cbb81d94ad networkCidr=10.0.1.0/24
Parameters¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
uuid | see Resource Properties | 0.6 | ||
name | see Resource Properties | 0.6 | ||
description | see Resource Properties | true | 0.6 | |
l3NetworkUuid | uuid of parent L3 network | 0.6 | ||
networkCidr | network CIDR; it must be in format of: network-number/prefix-length
|
0.6 |
Delete IP Range¶
Users can use DeleteIpRange to delete an IP range. For example:
DeleteIpRange uuid=b1cfcdeca4024d13ac82edbe8d959720
Warning
Deleting a IP range will stop all VMs that have IP addresses in the range. There is no way to recover a deleted IP range.
Parameters¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
uuid | IP range uuid | 0.6 | ||
deleteMode | see Delete Resources | true |
|
0.6 |
Add DNS¶
Users can use AddDnsToL3Network to add a DNS to a L3 network. For example:
AddDnsToL3Network l3NetworkUuid=50e637dc68b7480291ba87cbb81d94ad dns=8.8.8.8
Parameters¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
l3NetworkUuid | uuid of parent L3 network | 0.6 | ||
dns | dns IPv4 address | 0.6 |
Attach Network Service¶
After creating a L3 network and before creating any VMs on it, users can use AttachNetworkServiceToL3Network to attach network services to the L3 network. If a network service is attached to a L3 network that already has VMs running, the existing VMs can not use the network service until they are rebooted.
Note
In this ZStack version, detaching a network service from a L3 network is not supported.
For example:
AttachNetworkServiceToL3Network l3NetworkUuid=50e637dc68b7480291ba87cbb81d94ad networkServices='{"1d1d5ff248b24906a39f96aa3c6411dd": ["DHCP", "DNS", "SNAT", "EIP"]}'
Parameters¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
l3NetworkUuid | L3 network uuid | 0.6 | ||
networkServices | A map whose key is network service provider UUID and value is a list of network service types | 0.6 |
Note
You can use QueryNetworkServiceProvider to get the UUID of a network service provider, for example:
QueryNetworkServiceProvider fields=uuid name=VirtualRouter
If you want to view network services a provider provides, omit the parameter ‘field’, for example:
QueryNetworkServiceProvider name=VirtualRouter
Query L3 Network¶
Users can use QueryL3Network to query L3 networks. For example:
QueryL3Network dnsDomain=zstack.org
QueryL3Network vmNic.ip=192.168.10.2
Nested And Expanded Fields of Query¶
Field | Inventory | Description | Since |
---|---|---|---|
ipRanges | IP range inventory | IP ranges this L3 network contains | 0.6 |
networkServices | l3Network network service reference | network services attached to this L3 network | 0.6 |
l2Network | L2 network | parent L2 network | 0.6 |
vmNic | VM nic inventory | VM nics on this L3 network | 0.6 |
serviceProvider | network service provider inventory | network service providers that provides network services attached to this L3 network | 0.6 |
zone | zone inventory | ancestor zone | 0.6 |
L3 Network Tags¶
Users can create user tags on a L3 network with resourceType=L3NetworkVO. For example:
CreateUserTag resourceType=L3NetworkVO tag=web-tier-l3 resourceUuid=f6be73fa384a419986fc6d1b92f95be9
IP Range Tags¶
Users can create user tags on an IP range with resourceType=IpRangeVO. For example:
CreateUserTag resourceType=IpRangeVO tag=web-tier-IP resourceUuid=8191d946954940428b7d003166fa641e