Page 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
• modifyNic

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

...

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

...

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.

...

modifyNic

This command modifies 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

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

...

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

Response Parameters

...

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

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

Response Parameters

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

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.

...