The Jira issue associated with this design spec is CLOUDSTACK-1043 \ [1\] Wiki Markup
TBD
Wiki Markup |
---|
This design proposes to expose a virtual network interface card (NIC) as a first class object in the CloudStack API. The pattern follows that of the Amazon Elastic Network Interface \[2\]. |
The work is being carried out in branch standalone-nic, staged in a Github repository
https://github.com/siwater/cloudstack.
This design proposes to expose a virtual network interface card (NIC) as a first class object in the CloudStack API. The pattern follows that of the Amazon Elastic Network Interface [2].
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] have been made in the 4.1 release to allow a NIC to be added/removed from a virtual machine after 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. Wiki Markup
This design document proposes changes which expose a 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 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; clarify which NICs will be returned as a result of a list virtual machines command, and specify that the security groups for a NIC be listed:
...
This feature will add the capability for security groups associated with a NIC to be modifiedupdated. The old security group rules must be removed and the new security group rules applied in a secure fashion (i.e. don't drop the old rules and leave the NIC unprotected for a short period before the new rules are applied).
...
The internal architecture of CloudStack already has much of the plumbing in place to support the proposed API changes.following is a high level description of the changes made:
The nics table is extended to add account/domain information.
A new table security_group_nic_map is introduced to contain the set of security groups associated with a Nic
A new view entitled nics_view is introduced to support the listNics command.
The following API command classes have been introduced in the org.apache.cloudstack.api.command.user.nic namespace:
Extend NetworkService API to allow create/delete/update Nic
Extend UserVmService API to allow attach/detach of Nic from VM.
Extend QueryService API to allow search for Nics.
Introduce NicsJoinDao and NicsJoinVO classes to support query functions
Introduce SecurityGroupNicMapVO and SecurityGroupNicMapDao/Impl classes to provide access to the new security_group_nic_map table.
Implement create/delete/update Nic methods in NetworkServiceImpl
Implement attach/detach methods in UserVmManagerImpl
Implement search for Nics method in QueryManagerImpl
Add methods in VirtualMachineManager API to attach/detach Nic from VM and provide implementation in VirtualMachineManagerImpl (partially by restructure of existing code)
Change NetworkManager API profile of assignPubliIpAddress to take an Account object to represent the owner rather than a VM object. Involved minor changes to Network GurusThis section will be updated with Architecture and Design description as the required changes are identified.
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.
...
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 (mutually exclusive with securitygroupnames) | false |
securitygroupnames | Comma separated list of security group names to be associated with the NIC (mutually exclusive with securitygroupids) | false |
ipaddress | Primary IP address of the NIC. If not specified a primary IP address 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 addresses will be automatically allocated from the network range. Cannot be used in conjunction with secondaryipaddresses parameter | false |
ip6address | Primary IPv6 address 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 | The project in which to deploy the NIC | false |
...
Parameter | Description |
---|---|
displaytext | Any text associated with success or failure |
success | True if the operation succeeded |
...
This command modifies updates an existing NIC. The implementation must ensure that any security group rules associated with the NIC are safely adjusted (as the NIC may be connected to a virtual machine).
...
Parameter Name | Description | Required |
---|---|---|
id | The id of the NIC | true |
securitygroupids | Comma separated list of security group ids to be associated with the NIC (mutually exclusive with securitygroupnames) | false |
securitygroupnames | Comma separated list of security group names to be associated with the NIC (mutually exclusive with securitygroupids) | false |
Parameter Name | Description |
---|---|
nic | The NIC that has been attached (see NIC data object) |
...
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 a collection of NICs then she s/he may not also specify security groups for the virtual machine.
...
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 | ||
networkid | Id of the network to which NIC is connected | ||
networkname | Name of the NIC network | ||
securitygroup(*) | List of security groups associated with the NIC | ||
broadcasturi | URI | ||
instanceid | Id of the virtual machine to which NIC is attached | ||
netmask | IPv4 netmask | ||
gateway | IPv4 gateway | gateway | string |
ipaddress | Primary IP IPv4 address of the NIC | ||
isolationuri | Isolation URI | ||
broadcasturi | Broadcast URI | ||
traffictype | Traffic type | ||
type | Type of | 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 |
TBD
Appendix A:
macaddress | MAC address of the NIC |
ip6gateway | Address of IPv6 gateway |
ip6address | Primary IPv6 address of the NIC |
ip6cidr | IPv6 address CIDR of the NIC |
securitygroup(*) | List of security groups associated with the NIC |
secondaryipaddress(*) | List of secondary IP addresses for the NIC |
The required UI components are TBD.
The work will be undertaken in two phases:
This phase will implement the majority of the new functionality; adding the capabilities to create and delete NICs, attach and detach them from a virtual machine and provide a query (list) service to enumerate the NICs in the system. It will provide the ability to associate one or more security groups with a NIC (but not make any changes to how security groups are applied to a VM/Nic)
The completion of this phase will have little impact on the rest of the CloudStack system, as the new features will be relatively standalone. The idea is to be able to add the new code to the existing CloudStack codebase with relatively little risk, and be able to standalone test the new features before fully integrating them into the system.
This phase will integrate the standalone NIC code with the rest of the system. Any existing APIs will be modified at this stage, and where necessary commands will be merged (e.g. secondary IP address work has also introduced a "list NICs" command and an "update NIC" command which we may wish to combine with the ones produced here.
In addition the work will be carried out to modify the implementation of security groups so that they are applied to a virtual NIC only.
Unit tests are provided for the create and delete NIC commands
A collection of integration tests for the create/delete/list/attach/detach NIC commands are provided in the test/integration/smoke folder (see test_standalone_nic.py).
Testing to date has been limited to the XenServer platform.Appendix B: