Introduction

Amazon Web Services (AWS) provides EIP (Elastic IP) addresses which are static IP's that are associated with account which allows users to dynamically re-map to any instances they own [1][2]. ElP addresses allow to mask instance or availability zone failures by programmatically remapping to any instance account owns. Static allocation and dynamic remapping capabilities signifies the 'elasticity' in EIP and differentiates from the default dynamically allocated public ip for the instance. EIP combined with availability zone are used to build fail-over application architecture in AWS [3].

CloudStack provides users with ability to acquire zone level public IP's (that are static) in advanced zone that are associated with the account. Users also have control to create and recreate static nat with any instances they own. An acquired zone level public IP is associated with a guest network, so public IP can be used to associate with any instances in the guest network. With 'regions' and 'object store' vision of CloudStack, users would be able to launch instances across the zones. But there is no ability to transfer static public IP allocated to account across the zones to build a fail over strategy. It is desirable to bring the elastic characteristics of EIP in to CloudStack i.e) ability to transfer public IP across zones.

Goals

This proposal would like to introduce following functionality.

1. introduce a new category of public IP called 'portable public ip' that are provisioned by admin at region level and are available for user consumption
2. user's shall be able to acquire portable public IP if admin has provisioned portable public ip's at region level
3. acquired portable public IP shall be able to used by user for any service with in advanced zone
4. acquired portable public IP shall be usable for EIP service with in basic zone
5. acquired portable public IP can associated and disassociated with any virtual network and VPC.
6. acquired portable public IP association can be transferred from one network to another network

Document History

References

[1] http://aws.amazon.com/articles/1346

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

[3] 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

[4] http://docs.aws.amazon.com/AWSEC2/latest/APIReference/OperationList-query.html

[5] https://cwiki.apache.org/confluence/display/CLOUDSTACK/GSLB+(Global+Server+Load+Balancing)+Functional+specification+and+Design+Document

Functional requirements & non-requirements

• introduce notion of 'portable' public ip pool that will be associated with a region
• Admin be able to add/delete/list portable public IP range in to/from the region level portable public ip pool
• Users be able to acquire/release portable public ip
• Users be able to associate/disassociate portable public ip with an instance in advanced zone
• users be able to list the acquired public IP's
• admin be ables to list the portable public IP's provisioned
• support NetScaler as both source NAT and static NAT service provider
• users shall be able to associated a portable public IP with static nat, lb , fw, static NAT sercices

region level portable public ip detailed design

This section presents the detailed design for the region level portable public ip service functionality. 

User API

associateIPAddress

associateIpAddress shall be enhanced to acquire a portable IP from the pool of portable public IP's provisioned at region level

Request parameters:

• isPortable: boolean flag shall be introduced. if set to true, associateIpAddress api shall return public IP that is portable across the zones

API Response: IPAddressResponse response shall be enhanced to return 'isPortable' parameter, that indicated portable IP is portable or not

disassociateIpAddress

release of portable public IP shall be performed by disassociateIpAddress API. There are no changes required from API perspective.

Admin API

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

createPortableIpAddressRange

Request parameters:

• region id
• start ip
• end ip
• netmask
• gateway
• vlan

API Response: PortableIpRangeResponse 

deletePortableIpAddressRange

Request parameters:

• portable ip address range id

API response: will return 'SuccessResponse' on success

listPortableIpAddressRanges

Request parameters:

• id: elastic IP id. 
• region id

API Response: list of PortableIpRangeResponse objects

Api Response

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

• UUID: id of the portable public 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 portable public ip is associated with a VM
• zone id: UUID of the zone in which portable pubic ip is associated
• Vm id: UUID of the VM to which the portable public ip is associated
• Nic id: UUID of the Nic of the VM to which portable public ip is associated
• guest IP: guest Ip to which the portable public ip 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

allocatePortableIP: allocates a portable IP and associates portable IP to an account. Shall be called by associateIpAddress API when is_portable set to true. This method shall call allocatePortableIP method in network service layer.

releasePortableIpAddress: release portable ip association with an account. Shall be called by disassociateIpAddress API. This method shall call release public IP method in network manager.

Network Manager layer changes

- allocatePortableIp: allocates a portable IP from the range of portable IP's configured by admin. If admin has not provisioned portable IP's then then this method call shall fail.

- IP address release: dissociated a portable IP address with an account

- associatePortableIPToGuestNetwork: associates portable IP to a guest network

- disassociatePortableIPToGuestNetwork: disassociated a portable from a guest network. This new interface method shall only be called when 'isPortableIpTransferableFromNetwork' return true.

- isPortableIpTransferableFromNetwork: A new manager interface method shall be added. Should return true if portable IP is not associated with any services in a network. Returns false if portable IP is used for a purpose (firewall, LB, NAT, PF )

- Network delete: On network delete, default behaviour is to release the public IP's associated with the network. This behaviour shall be changed so that, portable IP shall be associated with the account. But portable IP shall be marked not associated with any network

RulesManager changes

• On a rule (PF/Static NAT/LB/FW) creation, if the public IP is portable shall be checked
• if public IP is a portable IP and is associated with a network, and API requests service in a different network then
  • check if portable is transferrable by calling isPortableIpTransferableFromNetwork
  • if portable is transferrable
    • call disassociatePortableIPToGuestNetwork to disassociate portable ip with guest network with which portable ip is currently associated
    • call associatePortableIPToGuestNetwork to associate IP with guest network where service is requested by API
    • raise a portable IP transfer event

Schema changes

'portable_ip_range' shall be added with following cloulmns

• UUID
• region ID
• vlan_id
• gateway
• netmask
• start_ip
• end_ip

'portable_ip_address' table shall be added with following columns

• account id: account id to which portable ip is associated
• domain id: domain id to which portable ip is associated
• region id: region id to which portable ip belongs
• data_center_id: zone to which portable ip is currently associated 
• network_id: network to which portable ip is associated
• state: indicated whether portable ip is allocated or free
• allocated: time stamp at which portable ip is allocated

'user_ip_address' table shall be enhanced with is_portable flag to indicate public ip is portable

Auditing

Action Events

When user transfers from portable IP from zone to another zone admin needs to be aware of the transfer so that required out-of-band actions can be taken. A new 'Action Event' shall be generated on every association and re-association of portable ip with a service in same zone or different zone with details of source and destination zone details.

Usage events

When a portable public IP is acquired or released an usage event shall be generated.