The Jira issue associated with this design spec [[TBD]]
TBD
This design proposes to expose a virtual NIC as a first class object in the CloudStack API. The pattern follows that of the Amazon Elastic Network Interface [1].
This design document describes changes which exposes the virtual network interface card (NIC) as a standalone entity in the CloudStack API that may be explicitly created/deleted and attached/detached from a virtual machine.
In CloudStack 4.0 release a virtual NIC is implicitly created when a virtual machine is deployed and connected to a network. Subsequent API changes [2] are proposed for the 4.1 release to allow a NIC to be added/removed from a virtual machine after creation
This feature will add the following new Platform API commands (User API).
In addition, the following API will be modified in a backward compatible manner, to allow a collection of NICs to be specified when deploying a new virtual machine:
Parameter profiles for the new and modified commands are described below (see Web Service API).
The main functional change arising from this proposal is that security groups, previously associated with a virtual machine will now be associated with a NIC.
The legacy semantics of the deployVirtualMachine operation will be preserved; if there are security groups specified as part of a deployVirtualMachine command then they will be associated with each of the NICs that get created as a result of that command. For example consider a system with two security groups (sg1 and sg2) and networks (net1 and net2). A command of the form
command=deployVirtualMachine&networkids=net1,net2&securitygroupsids=sg1,sg2
would result in two NICs being created, each of which would have security groups sg1 and sg2 associated with it.
put the relevant use case/stories to explain how the feature is going to be used/work
This command requests that a NIC be created and attached to a specified network in the system.
Parameter Name |
Description |
Required |
networkid |
The Id of the network that the NIC will be attached to |
true |
securitygroupids |
Comma separated list of security group ids to be associated with the NIC |
false |
ipaddress |
Primary IP address of the NIC. If not specified CS will automatically allocate a primary IP address from the network range |
false |
secondaryipaddresses |
Comma separated list of secondary IP addresses to be associated with the NIC. Cannot be used in conjunction with secondaryipaddresscount parameter |
false |
secondaryipaddresscount |
Number of secondary IP addresses required on the NIC – the addresses will be automatically allocated by CloudStack. Cannot be used in conjunction with secondaryipaddresses parameter |
false |
account |
The account owning the NIC |
false |
domainid |
The id of the domain in which the NIC should reside. If account is used, domainid must also be used. |
false |
projectid |
The project in which to deploy the NIC |
|
Parameter Name |
Description |
nic |
The NIC that has been created (see data objects) |
This command requests that a NIC be attached to a specified virtual machine.
Parameter Name |
Description |
Required |
id |
The id of the NIC |
true |
virtualmachineid |
The Id of the virtual machine that the NIC will be attached to |
true |
Parameter Name |
Description |
nic |
The NIC that has been attached (see data objects) |
This command requests that a NIC be detached from the specified virtual machine. The command will be rejected if this is the only NIC attached to the specified virtual machine.
Parameter Name |
Description |
Required |
id |
The id of the NIC |
true |
virtualmachineid |
The Id of the virtual machine that the NIC will be attached to |
true |
Parameter Name |
Description |
nic |
The NIC that has been detached (see data objects) |
This command requests a list of NICs.
Parameter Name |
Description |
Required |
id |
The Id of the NIC |
false |
account |
The account owning the NIC |
false |
domainid |
The id of the domain in which the NIC should reside. If account is used, domainid must also be used. |
false |
projectid |
List only NICs from this project |
|
isrecursive |
|
|
listall |
|
|
virtualmachineid |
List NICs for the specified virtual machine |
|
zoneid |
List NICs in the specified zone |
|
Parameter |
Description |
List<nic> |
List of NIC that match the search criteria (see data objects) |
This command requests that a NIC be deleted. The command will be rejected if the NIC is attached to a virtual machine
Parameter Name |
Description |
Required |
id |
The id of the NIC |
true |
Parameter |
Description |
displaytext |
Any text associated with success or failure |
success |
True if the operation succeeded |
The NIC object is described separately as it is returned from multiple commands.
Attribute |
Description |
id |
Id of the NIC |
*securitygroup* |
List of security groups associated with the NIC |
broadcasturi |
URI |
gateway |
string |
ipaddress |
Primary IP address of the NIC |
*secondaryipaddress* |
List of secondary IP addresses for the NIC |
isdefault |
Indicates if this the default NIC |
isolationuri |
URI |
macaddress |
string |
netmask |
string |
networkid |
string |
traffictype |
string |
type |
string |
The principle is that any changes to the existing API are required to be backward compatible – i.e. they should not break any existing clients of the API.
This command is modified to take an optional extra parameter:
Parameter Name |
Description |
Required |
nicids |
Comma separated list of NICs to attach to the virtual machine. The first NIC in the list will be designated as the default NIC. Cannot be used in conjunction with secuirtygroupnames, secutirygroupids, ipaddress, iptonetworklist or networkids parameters. |
false |
This commands request object is unchanged.
The syntax of the response object is unchanged, the description is changed.
Parameter |
Description |
securitygroups |
The set of security groups associated with the virtual machine's NICs is returned (i.e. only one instance of a security group is returned even if it is associated with more than one NIC). |
|
|
UI flow
Appendix A:
Appendix B: