THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
Page History
...
| Wiki Markup |
|---|
The Jira issue associated with this design spec is CLOUDSTACK-1043 \[1\] |
Branch
TBD
Introduction
...
| Wiki Markup |
|---|
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 \[3\] 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). :
- createNic
- deleteNic
- attachNic
- detachNic
- listNics
In 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, and clarify which NICs will be returned as a result of a list virtual machines command:
- deployVirtualMachine
- listVirtualMachines
- listSecurityGroups
Parameter profiles for the new and modified commands are described below (see Web Service API).
...
The legacy semantics of the deployVirtualMachine operation will be preservedbe 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 and a command of the form
| Code Block |
|---|
command=deployVirtualMachine&networkids=net1,net2&securitygroupsids=sg1,sg2 |
This command would result in two NICs being created, one attached to each of the specified networks. Each NIC would have security groups sg1 and sg2 associated with it.
Multiple IP address support
...
One scenario would allow an IaaS user to construct a to construct a long lived service at a defined network identity by creating a NIC and associating it with a virtual machine. During the life of the service it may be that an update of the virtual machine is required (e.g. to apply security patches). In this case the old virtual machine can be destroyed but the NIC NIC retained. When the new (patched) virtual machine is created it can be associated with the existing NIC and so and so continue to implement the service.
...
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. For all commands standard access rights checks will be used to ensure the caller has the right to perform the operation.
createNic
This command requests that a NIC be created and attached to a specified network in the system. Standard resource quotas will be used to limit the number of NICs that an account may create, and also the number of IP addresses that may be allocated.
Request Parameters
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 a primary IP address fwill will be automatically be allocated 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 . The addresses will be automatically allocated from the network range. 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 | false |
Response Parameters
Parameter Name | Description |
|---|---|
nic | The NIC that has been created (see data objects) |
attachNic
This command requests that a NIC be attached to a specified virtual machine. A NIC may be attached to at most one virtual machine. The implementation must ensure that any security group rules associated with the NIC are in place and active before the NIC is actually connected to the virtual machine.
Request Parameters
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) |
detachNic
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. Any security group rules associated with the NIC should be removed after the NIC is detached from the virtual machine.
Request Parameters
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 |
Response Parameters
Parameter Name | Description |
|---|---|
nic | The NIC that has been detached (see data objects) |
listNics
This command requests a list of NICs.
Request Parameters
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 | false |
isrecursive | false | |
listall | false | |
virtualmachineid | List NICs for the specified virtual machine | false |
zoneid | List NICs in the specified zone | false |
Response Parameters
Parameter | Description |
|---|---|
List<nic> | List of NIC that match the search criteria (see data objects) |
deleteNic
This command requests that a NIC be deleted. The command will be rejected if the NIC is attached to a virtual machine.
Request Parameters
Parameter Name | Description | Required |
|---|---|---|
id | The id of the NIC | true |
Response Parameters
Parameter | Description |
|---|---|
displaytext | Any text associated with success or failure |
success | True if the operation succeeded |
deployVirtualMachine
This command is modified to take an optional extra parameter that allows the caller to specify a collection of NICs to attach to the virtual machine. This parameter cannot be used with any of the legacy mechanisms for attaching a virtual machine to a network. In addition, if the the caller does specify does specify a collection of NICs then she may not also specify security groups for the virtual machine.
Request Parameters
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 securitygroupnames, secutirygroupids securitygroupids, ipaddress, iptonetworklist or networkids parameters. | false |
listVirtualMachines
This commands request object is unchanged. The The syntax of the response object is also unchangedunchanged, but the description is changed.
Response Parameters
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). |
listSecurityGroups
This command is modified to take an optional extra parameter that allows the caller to specify the NIC for which security groups are required. If specified the set of security groups associated with the NIC are returned.
Request Parameters
Parameter | Description | Required |
|---|---|---|
nicid |
|
|
NIC
The NIC data object is described here as a separate entity as it is returned as part of a number of responses.
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 |
UI flow
TBD
Appendix
Appendix A:
Appendix B:
Overview
Content Tools
Apps