The Jira issue associated with this design spec is CLOUDSTACK-1043 \ [1\] Wiki Markup
The work is being carried out in branch standalone-nic, staged in a Github repository
https://github.com/siwater/incubator-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\]. 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\] have been made in the 4.1 release to allow a NIC to be added/removed from a virtual machine after creation.
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 following is a high level commentary on 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.
...
Extend NetworkService API to allow create/delete/update Nic
Extend UserVmService API to allow attach/detach of Nic from VM.
...
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 i nUserVmManagerImplin UserVmManagerImpl
Implement search for Nics method in QueryManagerImpl
...
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) |
...
Attribute | Description |
---|---|
id | Id of the NIC |
networkid | Id of the network to which NIC is connected |
networkname | Name of the NIC network |
instanceid | Id of the virtual machine to which NIC is attached |
netmask | IPv4 netmask |
gateway | IPv4 gateway |
ipaddress | Primary IPv4 address of the NIC |
isolationuri | Isolation URI |
broadcasturi | Broadcast URI |
traffictype | Traffic type |
type | Type of the NIC |
isdefault | Indicates if this the default NIC |
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.