Introduction

introduce 'elasticity'

Purpose

Document History

References

\[1\] [http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html]

\[2\] [http://support.rightscale.com/09-Clouds/AWS/02-Amazon_EC2/Designing_Failover_Architectures_on_EC2/00-Best_Practices_for_using_Elastic_IPs_(EIP)_and_Availability_Zones]

\[3\]

Scope & Assumptions

Semantic differences from AWS EIP

Functional requirements & non-requirements

• introduce notion of 'EIP' pool that will be associated with a region
• Admin be able to add, delete, list the entries/range in to the EIP pool
• Users be able to acquire, release, associate, disassociate, transfer and list EIP's
• Users be able to associate EIP with any VM in either basic or advanced zone
• Support for NetScaler as EIP service provider is P1, VR is P2, but the design should be generic so any NAT provider can be enhanced to act of EIP service provider
• When EIP is transferred from VM in a zone to VM in another zone, CloudStack will not be responsible for the actual router advertisements but will provide a ways (alert, event etc) on which admin can act up on
• no support for the VPC

Detailed Design

User API

Current set of associateIpAddress, disassociateIpAddress API's used to acquire and release a public IP is restricted to zone level public IP. Also, associateIpAddress actually combines acquiring and associating the IP with a network. Once associated with a network, there is only disassociate operation available on public IP, so public IP association can not be changed from one network to another. Due to semantic differences its not best way to extend the existing set of API's dealing with public IP management to be extended to manage EIP pool of IP's. With this premise following set of API's shall be introduced.

allocateElasticIPAddress

acquires an EIP IP from the pool of elastic IP's provisioned at region level

Request parameters:

• account name; account that owns the EIP
• domain id: domain id of the account
• region id: region from which EIP shall be allocated

API Response: ElasticIpAddressReponse

releaseElasticIpAddress

release EIP acquired previously

Request parameters:

• id: elastic IP id

API response: will return 'SuccessResponse' on success. api call shall throw exception if the EIP still associated with a VM

associateElasticIpAddress

Associate acquired elastic IP with VM instance in a zone. 

Request parameters:

• id: elastic IP id
• vm instance id
• nic id
• vm guest Ip: guest IP associated with the specified VM and  Nic Id's
• reassociate: boolean flag to indicate if already assigned to another instance then re-associate the elastic IP with new VM instance. If 'false' and elastic IP is already associated with another vm instance then associateElasticIpAddress api call shall throw exception.

API Response: ElasticIpAddressReponse

disassociateElasticIpAddress

Request parameters:

• id: elastic IP id
• vm instance id

API response: will return 'SuccessResponse' on success

listElasticIpAddress

Request parameters:

• id: elastic IP id. 

API Response: list of ElasticIpAddressReponse objects

Admin API

Following administrator API shall be introduced to add/delete/list IP addresses in to/from EIP pool

createElasticIpRange

Request parameters:

• region id
• start ip
• end ip

API Response: list of ElasticIpAddressReponse objects

deleteElasticIpRange

Request parameters:

• region id
• start ip
• end ip

API response: will return 'SuccessResponse' on success

listElasticIpRange

Request parameters:

• region id

 API Response: list of ElasticIpAddressReponse objects

Api Response

'ElasticIpAddressReponse' shall be introduced as API response object with following details

• UUID: id of the elastic IP
• IP address
• region id
• state: state of the EIP (allocated, free, releasing)
• account name: name of the account to which EIP is associated
• domain id; UUID of the domain to which EIP is associated
• associated: true if EIP is associated with a VM
• zone id: UUID of the zone in which EIP is associated
• Vm id: UUID of the VM to which the EIP is associated
• Nic id: UUID of the Nic of the VM to which EIP is associated
• guest IP: guest Ip to which the EIP is associated

zone id, vm id, nic id, guest IP shall be not null only if 'associated' is true.  account name and domain id shall be not null only if state is allocated or releasing

Service Layer changes

A new service 'ElasticIPService' shall be introduced with following interface definition

Schema changes

Auditing

Action Events

When user transfers from EIP from zone to another zone admin needs to be aware of the transfer so that required out-of-band actions (for e.g enabling EIP to be advertised from the new zone etc.) can be taken. A new 'Action Event' shall be generated on every association and re-association of EIP with a VM in same zone or different zone with details of source and destination zone details.

Usage events

Upgrade

Risk/Open Issues