// Copyright 2012 Citrix Systems, Inc. Licensed under the
// Apache License, Version 2.0 (the "License"); you may not use this
// file except in compliance with the License. Citrix Systems, Inc.
// reserves all rights not expressly granted by the License.
// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
// Automatically generated by addcopyright.py at 04/03/2012
package com.cloud.network.guru;
import com.cloud.deploy.DeployDestination;
import com.cloud.deploy.DeploymentPlan;
import com.cloud.exception.ConcurrentOperationException;
import com.cloud.exception.InsufficientAddressCapacityException;
import com.cloud.exception.InsufficientVirtualNetworkCapcityException;
import com.cloud.network.Network;
import com.cloud.network.NetworkProfile;
import com.cloud.network.Networks.TrafficType;
import com.cloud.offering.NetworkOffering;
import com.cloud.user.Account;
import com.cloud.utils.component.Adapter;
import com.cloud.vm.NicProfile;
import com.cloud.vm.ReservationContext;
import com.cloud.vm.VirtualMachine;
import com.cloud.vm.VirtualMachineProfile;
/**
* - Designs a virtual network depending on the network offering.
* - Implements the virtual network when a virtual machine requires the network to be started.
*
* There can be multiple NetworkGurus in a CloudStack system. Each NetworkGuru
* resources when VMs are gone.
*
* A Network goes through the following life cycles through the NetworkGuru.
* - When a guest network is created, NetworkGuru is asked to "design" the network.
* This means the NetworkGuru checks the parameters such as cidr, gateway,
* vlan, etc and returns a network that can work with those paremeters.
* Note that at this point the network is only a virtual network. It has
* not been substantiated with resources, such as vlan, to make the network
* functional in the physical environment. At this stage, the network is in
* Allocated state.
*
* - When the first virtual machine is about to be started and requires network
* services, the guest network needs to have resources to make it usable
* within the physical environment. At this time, the NetworkGuru is
* called with the implement() method to acquire those resources.
*
* - For every virtual machine starting in the network, the NetworkGuru is
* asked via the reserve() method to make sure everything the virtual
* machine needs to be functional in the network is reserved.
*
* - For every virtual machine being stopped in the network, the NetworkGuru
* is informed via the release() method to make sure resources occupied
* by the virtual machine is released.
*
* - If all virtual machines within the network have been stopped, the guest
* network is garbage collected. When a guest network is garbage collected
* the NetworkGuru is informed via the shutdown() method to release any
* resources it allocated to that network.
*
* - When a guest network is being deleted, the NetworkGuru is informed via
* the trash() method.
*
*/
public interface NetworkGuru extends Adapter {
/**
* Cloud stack requires the NetworkGuru to design a guest network given
* the software packages Once a NetworkGuru returns the designed network,
* that NetworkGuru is forever associated with the guest network. It is
* very important for the NetworkGuru implementation to be very specific
* about the network it is responsible for designing. Things that can
* be used to make determination can be isolation methods, services
* provided on the guest network and the service provider that's on the
* guest network.
*
* If a network is already fully substantiated with the necessary resources
* during this design phase, then the state should be set to Setup. If
* the resources are not allocated at this point, the state should be set
* to Allocated.
*
* @param offering network offering that contains the package of services
* the end user intends to use on that network.
* @param plan where is this network being deployed.
* @param userSpecified user specified parameters for this network.
* @param owner owner of this network.
* @return Network
*/
Network design(NetworkOffering offering, DeploymentPlan plan, Network userSpecified, Account owner);
/**
* For guest networks that are in Allocated state after the design stage,
* resources are allocated when the guest network is actually being used
* by a virtual machine. implement() is called to acquire those resources.
*
* @param network network to be implemented.
* @param offering network offering that the network was created with.
* @param destination where the network is being deployed in.
* @return a fully implemented Network.
* @throws InsufficientVirtualNetworkCapcityException if there's not
* enough resources to make the guest network usable in the physical
* environment. At this time, the admin generally must be involved to
* allocate more resources before any more guest network can be implemented.
*/
Network implement(Network network, NetworkOffering offering, DeployDestination destination, ReservationContext context) throws InsufficientVirtualNetworkCapcityException;
/**
* Once a guest network has been designed, virtual machines can be
* created. allocated() is called for the NetworkGuru to design a nic
* that will make the virtual machine work within the guest network.
*
* @param network guest network that the virtual machine will be deployed in.
* @param nic nic information that the end user wants to set. The
* NetworkGuru should check this information with the guest
* network settings to make sure everything will work.
* @param vm virtual machine that is about to be deployed.
* @return NicProfile nic with all of the information
* @throws InsufficientVirtualNetworkCapcityException if there's
* insufficient capacity within the guest network.
* @throws InsufficientAddressCapacityException if there are not addresses
* to be assigned.
*/
NicProfile allocate(Network network, NicProfile nic, VirtualMachineProfile<? extends VirtualMachine> vm) throws InsufficientVirtualNetworkCapcityException, InsufficientAddressCapacityException, ConcurrentOperationException;
/**
* Once a guest network is implemented, then the virtual machine must
* be allocated its resources in order for it to participate within the
* guest network. reserve() is called for the NetworkGuru to make sure
* that works.
*
* @param nic nic that the vm is using to access the guest network.
* @param network guest network the vm is in.
* @param vm vm
* @param dest destination the vm is deployed to
* @param context Reservation context from which to get the owner, caller, and reservation id
* @throws InsufficientVirtualNetworkCapcityException if there's not enough
* resources.
* @throws InsufficientAddressCapacityException if there's not enough ip
* addresses.
* @throws ConcurrentOperationException if there are multiple operations
* happening on this guest network or vm.
*/
void reserve(NicProfile nic, Network network, VirtualMachineProfile<? extends VirtualMachine> vm, DeployDestination dest, ReservationContext context) throws InsufficientVirtualNetworkCapcityException, InsufficientAddressCapacityException, ConcurrentOperationException;
/**
* When a virtual machine is stopped, the NetworkGuru is informed via the
* release() method to release any resources.
*
* @param nic nic that the vm is using to access the guest network.
* @param vm virtual machine
* @param reservationId reservation id passed to it in the ReservationContext
* @return true if release is successful or false if unsuccessful.
*/
boolean release(NicProfile nic, VirtualMachineProfile<? extends VirtualMachine> vm, String reservationId);
/**
* When a virtual machine is destroyed, the NetworkGuru is informed via
* the deallocate() method to make sure any resources that are allocated
* are released.
*
* @param network guest network that the vm was running in.
* @param nic nic that the vm was using to access the guest network.
* @param vm virtual machine being destroyed.
*/
void deallocate(Network network, NicProfile nic, VirtualMachineProfile<? extends VirtualMachine> vm);
/**
* @deprecated This method should not be here in the first place. What does this really mean? Is it always persisted
* in the nic? When is it persisted in the nic? When is it called? No Idea.
* @param profile
* @param network
*/
@Deprecated
void updateNicProfile(NicProfile profile, Network network);
/**
* When no virtual machines are running in the network, the network is
* shutdown and all physical resources are released. The NetworkGuru is
* informed via the shutdown method().
*
* @param network guest network being shut down
* @param offering network offering the guest network was created with.
*/
void shutdown(NetworkProfile network, NetworkOffering offering);
/**
* When a guest network is destroyed, the NetworkGuru is informed via the
* trash() method to recover any resources.
*
* @param network guest network being destroyed.
* @param offering network offering the guest network was created with.
* @param owner owner of the network.
* @return true if trash was successful; false if not.
*/
boolean trash(Network network, NetworkOffering offering, Account owner);
void updateNetworkProfile(NetworkProfile networkProfile);
TrafficType[] getSupportedTrafficType();
boolean isMyTrafficType(TrafficType type);
}