Bug Reference

The Jira issue associated with this design spec is CLOUDSTACK-1043 [1]

Branch

The work is being carried out in branch standalone-nic, staged in a Github repository
https://github.com/siwater/cloudstack.

Introduction

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].

Purpose

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.

References

  1. JIRA Issue CLOUDSTACK-1043
  2. Amazon Elastic Network Interface
  3. Add/Remove Network to VM

Feature Specifications

New and modified Platform API

This feature will add the following new Platform API commands (User API):

  • createNic
  • deleteNic
  • attachNic
  • detachNic
  • listNics
  • updateNic

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:

  • deployVirtualMachine
  • listVirtualMachines
  • listSecurityGroups

The following API commands will also be modified to take an optional NIC id as parameter:

  • enableStaticNat
  • createPortForwardingRule

Parameter profiles for the new and modified commands are described below (see Web Service API).

Security Groups become property of NIC

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. When a NIC is created via the createNic command, zero or more security groups may be associated with the NIC.

The security group rules will be applied when a NIC is attached to a virtual machine, and will only affect traffic to/from the network to which the NIC is attached. For example if a NIC connected to network net1 has a security group that allows ingress on port TCP/80, then when it is attached to a virtual machine, the firewall rules will be changed to allow traffic on port TCP/80 from net1 into the virtual machine. This must have no effect on the ingress/egress rules being applied to other NICs on the virtual machine.

When a NIC is detached from a virtual machine the security group rules for that NIC will be removed from the system. Again, this must not affect security group rules being applied to any other NIC attached to the virtual machine.

This feature will add the capability for security groups associated with a NIC to be updated. 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).

Preserve legacy semantics

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) and a command of the form

 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.

Similarly the commands to enable static NAT and create port forwarding rule will retain the virtual machine id parameter to support existing applications, but they will be modified to allow a caller to specify a NCI id as an alternative.

Multiple IP address support

A NIC may have one or more IP addresses, one of which is designated as the primary address of the NIC. To be consistent with the existing API the caller may specify which IP addresses to use for the NIC, or may choose to allow CloudStack to automatically allocate IP addresses (see createNic command).

Extended metadata support

The instance metadata will be extended so an instance can query metadata for the NIC(s) attached to itself. For each NIC the network id, device id and security group ids will be query-able.

Schema for new metadata TBD

Upgrade path

The implementation will provide scripts and appropriate processes to migrate from an existing CloudStack deployment to one supporting this feature.

Use cases

The feature allows the IaaS user great freedom in creating virtual machines and attaching them to networks.

One scenario would allow an IaaS user 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 retained. When the new (patched) virtual machine is created it can be associated with the existing NIC and so continue to implement the service.

Architecture and Design description

The following is a high level description of the changes made:

Database Schema

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.

cloud-api

The following API command classes have been introduced in the org.apache.cloudstack.api.command.user.nic namespace:

  • CreateNicCmd
  • AttachNicCmd
  • DetachNicCmd
  • DeleteNicCmd
  • ListNicsCmd
  • UpdateNicCmd

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.

cloud-server

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 Gurus.

Web Services APIs

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 (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

Response Parameters

Parameter Name

Description

nic

The NIC that has been created (see NIC data object)

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

Response Parameters

Parameter Name

Description

nic

The NIC that has been attached (see NIC data object)

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 NIC data object)

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 NIC data object)

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

updateNic

This command 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).

Request Parameters

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

Response Parameters

Parameter Name

Description

nic

The NIC that has been attached (see NIC data object)

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 a collection of NICs then s/he 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 securitygroupnames, securitygroupids, ipaddress, iptonetworklist or networkids parameters.

false

listVirtualMachines

This commands request object is unchanged. The syntax of the response object is also unchanged, 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

The id of the NIC for which a list of security groups is required

false

enableStaticNat

This command is modified to take an optional extra parameter that allows the caller to specify the NIC for which the command is intended rather than the virtual machine id. Similarly the response object new specifies the NIC id.

Request Parameters

Parameter

Description

Required

nicid

The id of the NIC for the static NAT

false

Response Parameters

Parameter Name

Description

nicid

The id of the NIC that has been affected

createPortForwardingRule

This command is modified to take an optional extra parameter that allows the caller to specify the NIC for which the command is intended rather than the virtual machine id. Similarly the response object new specifies the NIC id.

Request Parameters

Parameter

Description

Required

nicid

The id of the NIC for the port forwarding rule

false

Response Parameters

Parameter Name

Description

nicid

The id of the NIC that has been affected

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

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

UI flow

The required UI components are TBD.

Appendix

Appendix A: Implementation Phases

The work will be undertaken in two phases:

Phase 1 - Implement NIC as a standalone entity

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.

Phase 2 - Integrate standalone NIC

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.

Appendix B: Testing

Unit Tests

Unit tests are provided for the create and delete NIC commands

Integration Tests

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.