THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
Page History
...
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.
Purpose
This design document describes changes which exposes the virtual network interface cards card (NICsNIC) as a standalone entities entity in the CloudStack API that may be explicitly created/deleted and attached/detached from a virtual machine.
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 are proposed for the 4.1 release to allow a NIC to be added/removed from a virtual machine after creation
Purpose
This design document proposes to expose a virtual NIC as a first class object in the CloudStack API, in a similar way to the Amazon Elastic Network Interface.
References
- Add
Document History
Glossary
Feature Specifications
...
- functional
- non functional: performance, scalability, stability, overload scenarios, etc
- corner cases and boundary conditions
- negative usage scenarios
...
- what new logging (or at least the important one) is introduced
- how to debug and troubleshoot
- what are the audit events
- list JMX interfaces
- graceful failure and recovery scenarios
- possible fallback or work around route if feature does not work as expected, if those workarounds do exist ofcourse.
- if feature depends other run-time environment related requirements, provide sanity check list for support people to run
...
- configuration parameters or files introduced/changed
- branding parameters or files introduced/changed
- highlight parameters for performance tweaking
- highlight how installation/upgrade scenarios change
...
- OS
- xenserver, hypervisros
- storage, networks, other
...
- list your evaluation of possible security attacks against the feature and the answers in your design* *
...
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:
- deployVirtualMachine
Parameter profiles for the new and modified commands are described below (see Web Service API).
The main functional change arising from this proposal is that security groups, previously associate with a virtual machine will now be associated with a NIC.
...
Use cases
put the relevant use case/stories to explain how the feature is going to be used/work
...
- discussion of alternatives amongst design ideas, their resources/time tradeoffs and limitations. Explain why a certain design idea is chosen over others
- highlight architectural patterns being used (queues, async/sync, state machines, etc)
- talk about main algorithms used
- explain what components are being changed and what the dependent components are
- regarding database: talk about tables being added/modified
- performance implications: what are the improvements or risks introduced to capacity, response time, resources usage and other relevant KPIs
- preferably show class diagrams, sequence diagrams and state diagrams
- if possible, publish signatures of all methods classes and interfaces implement, and the explain the object information of different classes
Web Services APIs
createNic
This command requests that a NIC be created and attached to a specified network in the system.
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 | false |
ipaddress | Primary IP address of the NIC. If not specified CS will automatically allocate a primary IP address 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 by CloudStack. Cannot be used in conjunction with secondaryipaddresses parameter | 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 |
Response Parameters
Parameter Name | Description |
nic | The NIC that has been created (see data objects) |
attachNic
This command requests that a NIC be attached to a specified 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 data objects) |
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
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 data objects) |
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 | |
isrecursive | ||
listall | ||
virtualmachineid | List NICs for the specified virtual machine | |
zoneid | List NICs in the specified zone |
Response Parameters
Parameter | Description |
List<nic> | List of NIC that match the search criteria (see data objects) |
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 |
API Data Objects
The NIC object is described separately as it is returned from multiple commands.
NIC
Attribute | Description |
id | Id of the NIC |
securitygroup()* | List of security groups associated with the NIC |
broadcasturi | URI |
gateway | string |
ipaddress | Primary IP address of the NIC |
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 |
Existing API
The principle is that any changes to the existing API are required to existing web services APIs and new APIs introduced with signatures and throughout documentation
UI flow
be backward compatible – i.e. they should not break any existing clients of the API.
deployVirtualMachine
This command is modified to take an optional extra parameter:
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 ipaddress, iptonetworklist or networkids parameters. | false |
UI flow
- TBDeither demonstrate it visually here or link to relevant mockups
Appendix
Appendix A:
Appendix B:
Overview
Content Tools
Apps