AWS Style NIC support

Bug Reference

The Jira issue associated with this design spec.

Branch

TBD

Introduction

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

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 [2] are proposed for 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. Amazon Elastic Network Interface
2. Add/Remove Network to VM

Document History

Glossary

Feature Specifications

New and modified Platform API

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

• createNic
• deleteNic
• attachNic
• detachNic
• listNics

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

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.

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

This command would result in two NICs being created, each of which would have security groups sg1 and sg2 associated with it. 

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

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 internal architecture of CloudStack already has much of the plumbing in place to support the proposed API changes.

This section will be updated with Architecture and Design description as the required changes are identified.

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.

createNic

This command requests that a NIC be created and attached to a specified network in the system.

Request Parameters

Response Parameters

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.

Request Parameters

Response Parameters

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.

Request Parameters

Response Parameters

listNics

This command requests a list of NICs.

Request Parameters

Response Parameters

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

Response Parameters

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 she may not also specify security groups for the virtual machine.

Request Parameters

listVirtualMachines

This commands request object is unchanged. The syntax of the response object is also  unchanged, but the description is changed.

Response Parameters

NIC

The NIC data object is described here as a separate entity as it is returned as part of a number of responses.

UI flow

TBD

Appendix

Appendix A:

Appendix B: