Optional Public IP assignment for EIP with Basic Zone

Introduction

In basic zone CloudStack provides AWS EIP like functionality using static NAT (1:1 NAT) from public IP to VM's private IP. Below are the semantics of EIP as implemented in CloudStack.

When a user VM is deployed, a public ip is automatically acquired from the pool of public IP configured in the zone. This IP is owned by the vm's account and is marked as 'system' in the db.
When the user VM starts, static NAT is provisioned on the static NAT provider between the public ip and the guest ip of the vm.
The user can also acquire a public ip by calling the associateIp API. When this api call returns, there is a public ip associated with the account, but not mapped to any guest ip.
The IP acquired in #3 can be static NAT'ed to the VM deployed in #1 by calling enableStaticNat API. This causes the IP allocated in #1 to be returned to the public ip pool. The static NAT rules configured on the Static NAT provider are re-programmed to carry out the new mapping.
The public IP with static NAT enabled in #4 can be removed from static NAT by calling the disableStaticNAT API. This causes the Static nat provider to remove the static nat rule. A new public IP is allocated (not necessarily the same as the one allocated in #1 and static NAT'ed with the guest IP of the VM.
When the VM is stopped, if the ip address has isSystem=true(allocated during the vmDeploy) then public Ip is removed from the static NAT mapping and released into public pool.

In this semantics, by default a public IP is allocated for each VM created in basic zone with EIP service. For deployments where public IP's are scarce resource, allocating public IP for each VM will be expensive. Currently there is no provision in the CloudStack to modify this behaviour. This proposal provides flexibility to the cloud admins, where they can choose not to allocate public IP to the VM by default when using EIP service in basic zone. Below is the description of API, DB and EIP semantics changes that shall be required to achieve this flexibility.

'Bug : 265 provide option to turn-off automatic public IP assignment for each VM when using EIP service' is opened to track this feature.

API changes:

With createNetworkOffering API, we can specify the set of network services and network service capabilities. A capability of Static NAT service will be the right place to provide the admin to make a choice to allocate a public IP by default or not. A new capability 'AssociatePublicIP' shall be introduced to set of network service capabilities provided by the CloudStack.
'AssociatePublicIP' capability will be used only with 'Static NAT' service and along with 'Elastic IP' capability only. When 'AssociatePublicIP' capability is specified for network services other than 'Static NAT' or when 'Elastic IP' capability is not specified, in those cases it will have no relevance and createNetworkOffering() API shall fail and throw invalid parameter value exception.
A network offering with guest type traffic 'shared' with Static NAT service and EIP capability with ability to assign a public IP with each user VM is created as

http://management server IP:8080/client/api?command=createNetworkOffering&response=json&name=EIP-offering-with default-publicIP&displayText=EIP-offering-with-default-publicIP&guestIpType=Isolated&

servicecapabilitylist[0].service=StaticNat&servicecapabilitylist[0].capabilitytype=ElasticIp&servicecapabilitylist[0].capabilityvalue=true&servicecapabilitylist[1].service=StaticNat&servicecapabilitylist[1].capabilitytype=AssociatePublicIP&servicecapabilitylist[1].capabilityvalue=true&

supportedServices=Dhcp,Dns,Firewall,SourceNat,StaticNat&specifyVlan=false..................(rest of the parameters)..........

A network offering with Static NAT service and EIP capability which ensures that no public IP is assigned to the VM is created as

http://management server IP:8080/client/api?command=createNetworkOffering&response=json&name=EIP-offering-with default-publicIP&displayText=EIP-offering-with-default-publicIP&guestIpType=Isolated&

servicecapabilitylist[0].service=StaticNat&servicecapabilitylist[0].capabilitytype=ElasticIp&servicecapabilitylist[0].capabilityvalue=true&servicecapabilitylist[1].service=StaticNat&servicecapabilitylist[1].capabilitytype=AssociatePublicIP&servicecapabilitylist[1].capabilityvalue=false&

supportedServices=Dhcp,Dns,Firewall,SourceNat,StaticNat&specifyVlan=false..................(rest of the parameters)..........

listNetworkOfferings API shall return the value set for the capability 'AssociatePublicIP' if configured in the network offering.
UserVMResponse object returned by listVMs API shall have the 'publicIP' param populated only if the network offering used to create basic zone shared network has the AssociatePublicIP capability set to true. If the AssociatePublicIP capability is set to false then UserVmResponse returned by listVMs API shall have 'publicIP' param set to null.

Schema Change:

In the 'network_offerings' table new boolean column named 'eip_associate_public_ip' shall be introduced with below schema change.

`eip_associate_public_ip` int(1) unsigned NOT NULL DEFAULT 0 COMMENT 'true if public IP is associated with user VM creation by default when EIP service is enabled.',

If in the network offering used to create shared network in the basic zone has the 'eip_associate_public_ip' column set to true, then for each VM launched in the basic zone a public IP is associated with VM by default. If in the network offering used to create shared network in the basic zone has the 'eip_associate_public_ip' column set to false, then by default a VM launched in the basic zone will only have a private IP and no public IP will be associated with it.

CreateNetworkOffering API called with AssociatePublicIP capability set to TRUE shall result in creating network offering in the DB with eip_associate_public_ip column set to 1. CreateNetworkOffering API called with AssociatePublicIP capability set to FALSE shall result in creating network offering in the DB with eip_associate_public_ip column set to 0.

EIP semantic changes:

EIP semantics are modified as below:

When a user VM is deployed in the basic zone with EIP service enabled
1. if the shared network is created with network offering that has 'eip_associate_public_ip' column set to 1 then a public ip is automatically acquired. This IP is owned by the vm's account and is marked as 'system' in the db. Static NAT rule is provisioned on the Static NAT provider that maps public IP to VM's private IP.
2. if the shared network is created with network offering that has 'eip_associate_public_ip' column set to 0, then VM is provisioned only with private IP. No static NAT rule is provisioned on the static NAT provider.
The user can acquire a public ip by calling the associateIp API. When this api call returns, there is a public ip associated with the account, but not mapped to any guest ip.
The IP acquired in #2 can be static NAT'ed to the VM deployed in #1 by calling enableStaticNat API. If there is a public IP associated with VM in step #1, then this causes the IP to be returned to the public ip pool. The static NAT rules configured on the Static NAT provider are re-programmed to carry out the new mapping.
The public IP with static NAT enabled in #3 can be removed from static NAT by calling the disableStaticNAT API. This causes the Static nat provider to remove the static nat rule.
1. A new public IP is allocated (not necessarily the same as the one allocated in #1 and static NAT'ed with the guest IP of the VM if the shared network is created with network offering that has 'eip_associate_public_ip' column set to 1.
2. no public IP is allocated if network offering has 'eip_associate_public_ip' column set to 0.
When the VM is stopped, if there is public IP associated with the VM either from #1, #4.a and ip address has isSystem=true(allocated during the vmDeploy) then public Ip is removed from the static NAT mapping and released into public pool.

System VM's

This feature should affect EIP semantics with respect to user VM's only. System VM's should continue to get both public IP and private by default irrespective of 'eip_associate_public_ip' is set or not in the network offering that is used to create a basic zone with EIP and ELB service.

Upgrade

For the existing basic zone deployments with EIP service, current behaviour is to assign a public IP with every user VM. After upgrade, existing functionality will be retained. So on upgrade network offerings with EIP service enabled shall be updated so that 'eip_associate_public_ip' column of of the network_offerings table is set to 1.

Changes to default network offering with EIP & ELB service

The default network offering created by CloudStack, for created shared networks with EIP and ELB service shall be updated so that network offering will have eip_associate_public_ip set to true. So the new deployments which uses default shared network offering with EIP and ELB service to create shared network in the basic zone, shall result in the old EIP semantics to the users, i.e. a public IP is allocated by default to each user VM.

UI Changes

Create network offering dialog box should have capability 'associate IP address' checkbox that is available in the UI when EIP service capability is chosen. Checkbox for the capability shall only show up when 'EIP service' capability is choosen.

when the checkbok checked should result in a createNetworkOffering API with AssociatePublicIP parameter is passed and value set to true

when the checkbok un-checked should result in a createNetworkOffering API with AssociatePublicIP parameter is passed and value set to false

Space shortcuts

Child pages