Backward compatibility risk areas in the API

BMC Cloud Lifecycle Management version 3.0 contains several major changes to the API. BMC has a policy of maintaining backward compatibility with previous versions of the API. However, this policy does not guarantee that existing customizations that use the API will not need changes to take advantage of new features. This topic provides an overview of the changes and highlights the risk areas.

Cloud API changes

In version 3.0, some of the core model and, therefore, some API assumptions, have changed. As a result of these changes, old parts of the model have been deprecated. Deprecated APIs work with old objects, but might not work with new objects. This is a core risk for field use of the API. Because core assumptions have changed, code written against the old assumptions might need to be adapted to the new assumptions. Preexisting objects satisfy the old assumptions, so the APIs are guaranteed to work against those objects.

To better understand the deprecation issues, consider the following example: suppose you have a customization that includes API calls to find the names of all networks in a network container. To find network containers that do not have zones — a new capability in version 3.0 — this customization must be modified. However, this customization continues to function correctly when used with network containers that were created in BMC Cloud Lifecycle Management 2.1 and upgraded to version 3.0.

Version 3.0 maintains the old relationships and attributes for each API and returns them when an object is retrieved by search or by GET requests. However, because the API implementation ignores old relationships and attributes during PUT and POST requests, any customizations that use these features must be modified to call the equivalent new APIs (see Model changes).

Firewall and load balancer management changes

Existing customizations that involve firewall and load balancer management might need to be modified. In version 2.1, FirewallRule, LoadBalancerPool, and LBPoolEntry class objects are not persisted in the CloudDB and can be read only from the object provider. In version 3.0, these objects are persistent first-class objects. Because of this change, search requests involving these objects might need to be modified.

The sequence of calls that you must use to support concurrency during firewall modifications has changed. The following table shows the version 2.1 and version 3.0 flows for firewall modifications. Because the sessionGuid attribute of the Firewall class is deprecated, you must now acquire the sessionGuid attribute from the NetworkContainer object. The POST /csm/Firewall/<guid>/replaceRulesForIP request is deprecated, but functions for version 2.1 network containers that have been upgraded. However, to use any newly-created containers, you must use the new APIs (see Model changes).

Version 2.1 versus version 3.0 firewall modification flow

Step	Version 2.1 firewall modification flow	Version 3.0 firewall modification flow
1	Get the list of firewall rules on a firewall and retrieve the `sessionGuid` from the firewall.	Call `POST /csm/NetworkContainer/guid/acquireLock`, which returns the `sessionGuid`.
2	Not applicable	Get the list of firewall rules on a firewall network interface.
3	Call `POST /csm/Firewall/<guid>/replaceRulesForIP`, passing in the `sessionGuid`.	Call `POST /csm/FirewallNetworkInterface/<guid>/replaceInboundRules` or `POST /csm/FirewallNetworkInterface/<guid>/replaceOutboundRules`, passing in the `sessionGuid`.
4	Not applicable	Call `POST /csm/NetworkContainer/<guid>/releaseLock`, passing in the `sessionGuid`.

Model changes

The following table summarizes the changes to the model, and lists the deprecated APIs and corresponding new APIs.

Tip

If you can't see the rightmost column of the following table, click Hide left column or type [. If you are using Safari on a Mac and still cannot see the rightmost column, try using Firefox.

Summary of model changes

Model change	Deprecated APIs	New APIs
The `NetworkInterface` class now has the following subclasses: `LoadBalancerNetworkInterface`, `FirewallNetworkInterface`, and `ServerNetworkInterface`. `NetworkInterface` remains a concrete class for backward compatibility.	The relationship between `NetworkInterface` and `Server` is deprecated, but remains available for backward compatibility.	A new relationship between `Server` and `ServerNetworkInterface` replaces the deprecated relationship.
Firewalls no longer belong to a single zone. Instead, they have interfaces on networks and belong to network containers.	`GET csm/Zone/<guid>/firewall` Searches that involve the zone-firewall relationship are also deprecated.	`GET csm/Zone/<guid>/networks/networkInterface` followed by `GET csm/FirewallNetworkInterface/<guid>/firewall`
Load balancers no longer belong to a single zone. Instead, they have interfaces on networks and belong to network containers. These interfaces are either client or server interfaces, representing the client side or server side of the load balancer.	`GET csm/Zone/<guid>/loadBalancer`	`GET csm/Zone/<guid>/networks/networkInterface` followed by `GET csm/LoadBalancerNetworkInterface/<guid>/clientLoadBalancer` and `GET csm/LoadBalancerNetworkInterface/<guid>/serverLoadBalancer`
Firewalls are no longer assumed to have a single inbound access control list (ACL), but instead have inbound and outbound ACLs on each interface. Version 3.0 persists firewall rules in the CloudDB, eliminating the need for a live search, which previously was the only way to look at these rules by using the API. Version 3.0 adds the following new `FirewallRule` subclasses: `InboundFirewallRule` and `OutboundFirewallRule`. `FirewallRule` remains a concrete class to support deprecated APIs.	`POST /FirewallRule/search` (with a criteria that includes `firewall.name`) `POST csm/Firewall/<guid>/replaceRulesForIP` This operation now works only for firewalls that have a single inbound ACL on a single interface. `POST csm/FirewallRule`	`POST csm/InboundFirewallRule/search` (with a criteria that includes `FirewallNetworkInterface.firewall.name`) and `POST csm/OutboundFirewallRule/search` (similar criteria) `POST csm/FirewallNetworkInterface/<guid>/replaceInboundRules` or `POST csm/FirewallNetworkInterface/<guid>/replaceOutboundRules`. Each operation takes a list of firewall rules. `POST csm/InboundFirewallRule` or `POST csm/OutboundFirewallRule` Because version 3.0 persists these objects in the CloudDB, you can now perform: `GET csm/Firewall/<guid>/networkInterface` followed by `GET csm/FirewallNetworkInterface/<guid>/inboundFirewallRule` or `GET csm/FirewallNetworkInterface/<guid>/outboundFirewallRule`.
Load balancer pools are now persisted in the CloudDB and point to the actual networks via their parent `LoadBalancerNetworkInterface` objects instead of having an ambiguous network label. Load balancer pools can now serve more than one server-side network.	`POST csm/LoadBalancer/search` (with a search criteria that includes loadBalancer.name) The `networkLabel` attribute returned in the `LoadBalancerPool` object is deprecated. Formerly, it represented the network label of the single server-side network.	You can retrieve the client network (single) that the load balancer pool is on by using: `GET csm/LoadBalancerPool/<guid>/clientNetworkInterface/network`. Note: Be careful. You might be tempted to traverse the server and client network interfaces to get an IP address, but that method does not work because the interfaces are `LoadBalancer` objects that are merely referenced by the `LoadBalancerPool` object. To get the virtual IP (VIP) of the load balancer pool, continue to use the `virtualIPAddress` attribute. The deprecated `networkLabel` attribute is replaced by a relationship traversal that directly retrieves server-side networks: `GET csm/LoadBalancerPool/<guid>/serverNetworkInterface/network`.
`LBPoolEntry` objects are now persisted in the CloudDB and point to the actual network interface on the servers that they serve.	`POST csm/LPPoolEntry/search` Use a search criteria that includes `LoadBalancerPool.LoadBalancer.name`.	You can now use relationship traversal to retrieve `LBPoolEntry` objects from `LBPool` objects. Also, you can traverse from the `LBPoolEntry` object to the `ComputeContainer` and vice versa.
Zones are now optional. Network containers have parent-level networks. If zones exist, they can own their own networks.	No API is deprecated per se. However, `GET csm/NetworkContainer/<guid>/zones/networks` is no longer guaranteed to return all networks in the container.	You can now get the container level networks by requesting `GET csm/NetworkContainer/<guid>/network`.
The software no longer assumes that network labels are unique within a container. Network labels must be unique among all container-level networks and must be unique within each zone. This implies that in a network container with N zones, up to N+1 networks might have the same network label.	None	None
Version 3.0 does not model the total VLANs for a network	The `totalVLANS` attribute of the `Network` class is deprecated.	None
Logical communication paths is a new concept for end users. In the UI, this concept is called a network path. This concept replaces `FirewallRule` class APIs for end users. FirewallRule APIs now function only for tenant administrator users.	No APIs are deprecated, but firewall rule APIs do not function for end users.	To create a logical communication path, use `POST csm/LogicalCommunicationPath`. Pass endpoints (such as networks, load balancer pools, server NICs, and so on) in the body of the message. To delete a logical communication path, use `DELETE csm/LogicalCommunicationPath`.
A new object called a logical hosting environment, which has logical networks and other objects parallel to a network container, replaces network containers for the purpose of tagging and tenant mapping. A logical hosting environment maps to either a network container or a logical data center, which represents a VMware Organizational VDC.	`POST csm/NetworkContainer` `PUT csm/NetworkContainer`	`POST csm/LogicalHostingEnvironment` Pass a nested `NetworkContainer` object in the message body. `POST csm/LogicalHostingEnvironment/<guid>/update` Pass a nested `NetworkContainer` object in the message body.

Provider API changes

The approach to backward compatibility for the Provider API is different from the approach for the Cloud API because the Provider API is a southbound API. Version 3.0 contains many enhanced features, which cause the resource providers to have new behaviors. Most of the changes belong to the following categories: resource onboarding, container provisioning, and service provisioning. The primary feature responsible for these changes is the networking feature, in which the introduction of dynamic containers has changed the features that are expected from network and compute providers. The following sections describe changes in those categories, and changes to some algorithms that call the Provider API.

Resource onboarding changes

The version 3.0 resource onboarding flow is similar to the version 2.1 flow, but includes some new return values. The following table shows the differences (new features are listed in italics):

Version 2.1 versus version 3.0 resource onboarding flow

Step

Version 2.1 flow

Version 3.0 flow

1

Onboard a pod.

Return minimal information about the pod — a name and an external ID.

Onboard a pod.

Return information about the access switches in the pod (such as Cisco Nexus 1000V, VMware vSwitch, and Open vSwitch switches).

2

Onboard a container blueprint.

Return pod compatibility information.

Onboard a container blueprint.

Return pod compatibility information.
Return a template network container that describes the containers that this blueprint can create (including information such as how many networks, zones, firewalls, and default IP ranges).

3

Onboard a virtual cluster or physical server into a pod.

No pod compatibility information is returned.
Return virtual resource pools and hosts in the cluster, if appropriate.

Onboard a virtual cluster or physical server into a pod.

Return a list of switches that the cluster or server uses. The names of the switches match the names used in the pod. The list can be a subset of the switches in the pod.
Return virtual resource pools and hosts in the cluster if appropriate.

The key changes in resource onboarding are:

A pod must have at least one access switch.
Each compute resource (cluster or physical server) must be connected to the same switches used in the pod, and the switch names must match the names used in the pod.
A container blueprint must have a template network container.

The following table lists the changes to the associated Provider APIs:

Changes in the Provider API for resource onboarding

Provider API	Description of change
`POST /csm/Pod/onboard`	The HTTP response JSON contains a list of one or more `Switch` objects. In addition, pod-level networks should have an associated `SwitchPort` object.
`POST /csm/ContainerBlueprint/onboard`	The HTTP response includes a nested `NetworkContainer` object with its `isTemplate` attribute set to true. Any container-level networks should be there, with appropriate information about whether the network is dynamic or static.
`POST /csm/VirtualCluster/onboard`	The HTTP response includes a list of `Switch` objects for the virtual cluster. Each `Switch` object includes the name of a switch that belongs to the pod into which the virtual cluster is being onboarded, and the `guid` of the `VirtualInfrastructureManager` object (for example, a VMware vCenter Server or XenCenter).
`POST /csm/PhysicalServer/onboard`	The HTTP response includes a `SwitchPort` object and nested `Switch` object for each network interface on the physical server. Each switch belongs to the pod into which the physical server is being onboarded.

Network container provisioning changes

The changes in network container provisioning are due to the introduction of dynamic network containers and changes in the object model. Dynamic network containers affect the API input parameters because the software uses cloud administrator input for IP address information, enabled and disabled networks, and so on. Changes were made to the object model to reduce the importance of zones. For example, firewalls are no longer in a single zone and no longer represent a single real interface. As such, both the input and the output of the Provider API calls have changed.

Changes in the Provider API for network container provisioning

Provider API

Description of change

POST /csm/NetworkContainer

The input is now a much richer model that includes objects such as container-level (zone-free) networks, IP ranges set per network, firewalls with interfaces attached to networks and outside of zones, and load balancers with interfaces attached to networks. The response refers by name to switches that are in the pod and to a switch port for each network. Platform Manager will fail to create the container if the switches do not match.

SOI provisioning changes

Changes to service offering instance (SOI) provisioning are due to the introduction of dynamic containers, zone relaxation, and multi-ACL firewalls. The following table shows the differences between the version 2.1 and version 3.0 provisioning flows (new actions are listed in italics).

Version 2.1 versus version 3.0 SOI provisioning flow

Step	Version 2.1 flow	Version 3.0 flow
1	Call `NetworkConnector` constructor for each virtual machine (VM) or physical server NIC. Pass in `NetworkLabel` as the input. Return the VLAN-ID and the `PortTypeName` (and IP address for static IP NICs).	Call `NetworkConnector` constructor for each VM or physical server NIC. Pass in the `SwitchPort` with nested `Switch` for each NIC. Return the VLAN-ID and the `PortTypeName` (and IP address for static IP NICs)
2	Call `VirtualGuest` constructor or `OperatingSystem` constructor. Pass in the `PortTypeName` as a string for each NIC (and IP address for static IP NICs). Pass in the appropriate `VirtualCluster`, `VirtualResourcePool`, `VirtualHost`, or `PhysicalServer`. Return `VirtualGuest` or `OperatingSystem` with appropriate values, including IP addresses for Dynamic Host Configuration Protocol (DHCP) NICs.	Call `VirtualGuest` constructor or `OperatingSystem` constructor. Pass in the `PortTypeName` as a string for each NIC (and IP address for static IP NICs). Pass in the appropriate `VirtualCluster`, `VirtualResourcePool`, `VirtualHost`, or `PhysicalServer`. Return `VirtualGuest` or `OperatingSystem` with appropriate values, including IP addresses for DHCP NICs.
3	Not applicable	Call `POST /csm/NetworkContainer/<guid>/acquireNATAddress` for any server NICs that need a network address translation (NAT) address.
4	Call `BaseCPUSensor` and `BaseMemorySensor` onboard	Call `BaseCPUSensor` and `BaseMemorySensor` onboard.
5	Call `LBPool` constructor one or more times.	Call `LBPool` constructor one or more times.
6	Call `LBPoolEntry` constructor one or more times.	Call `LBPoolEntry` constructor one or more times.
7	Call `FirewallRule` constructor one or more times.	Call `NetworkPath` constructor one or more times.

Changes in the Provider API for SOI provisioning

Provider API	Description of change
`POST /csm/NetworkConnector/bulkCreate`	The API now takes a list of `DeploymentParameterValue` objects, the `NetworkContainer`, the `Server` (that is, the `VirtualGuest` or `PhysicalServer`), and the `ServerNetworkInterface`. `Zone` is no longer passed. The `ServerNetworkInterface` object has a relationship to a `Network` object which might have a relationship to a `Zone` object. The `ServerNetworkInterface` has a relationship to a `SwitchPort` which has a relationship to a `Switch`. This in particular matters for providers that manage unsupported switches such as Open vSwitch.
`POST /csm/NetworkContainer/<guid>/acquireNATAddress`	If your provider supports containers with NAT, you must implement this new call.
`POST /csm/NetworkPath`	This new call replaces the call to `POST /csm/FirewallRule`.

Callout API changes

The core piece of the Callout API, registration of a new callout, does not have any changes in version 3.0. However, because callouts receive data from either the Cloud API or the Provider API, depending on the API call to which they are attached, some risk exists in backward compatibility for callouts. This section summarizes the risks and highlights the risk mitigation factors.

High-risk areas for callouts attached to Cloud APIs

Most callouts attached to Cloud APIs remain unaffected, except for callouts that, in their implementation, depend on the network container topology. For example, a callout attached to POST /csm/ServiceOfferingInstance/bulkCreate that looks up all network containers for the tenant will work. However, if the callout then looks into the network containers to find all load balancers, the callout might fail. If a version 3.0 network container exists for the tenant, the callout might not function correctly. Similarly, for callouts attached to the network container creation APIs, all input arguments are exactly the same. However, if the callout needs to introspect a network container in the system via the Cloud API, it might not function correctly. Success or failure of the callout depends on what you are looking for.

Low-risk areas for callouts attached to Cloud APIs

Callouts that do not look into the network container part of the system and look only in the compute part of the system have lower risk. For example, a callout attached to the POST csm/ComputeContainer/start API that looks up the IP Address of the second NIC in the compute container functions correctly in version 3.0. Similarly, a callout attached to POST /csm/ServiceOfferingInstance/bulkCreate that looks up all the IP addresses of all the compute containers continues to function.

High-risk areas for callouts attached to Provider APIs

The changes to the Provider APIs are dramatic in version 3.0. Thus, most of the callouts attached to Provider API calls are at risk. Some of the risk is syntactical and some of the risk is semantic. The biggest risk areas are around networking, however the risk is present in all areas of the Provider API.

For an example of a callout that might seem on the surface to be unaffected syntactically, consider a callout that is attached to the POST /csm/VirtualGuest API. The callout introspects all the NICs to see all the IPs that the VM has acquired, either through IPAM or DHCP (it can do this if it is a post-callout to the API). In version 2.1, when the virtual guest create API call finishes, all IP addresses are reserved. However, in version 3.0, all IP addresses are not reserved when the call finishes because a new Provider API call that handles NAT is invoked after the virtual guest create API call finishes. Thus, a callout that depends on having a complete picture of the reserved IP addresses does not function correctly in version 3.0, even though it still can see all the IP addresses on the VM.

Low-risk areas for callouts attached to Provider APIs

At the Provider API level, low-risk areas are few and far between. However, in some cases, such as finding information about VMs or physical servers (for example, the host name and IP addresses), and in the absence of any use of NAT features, these callouts function correctly. For example, a callout that registers a VM in Active Directory can find the VM IP addresses in version 3.0 and does not require modification. As long as the VM IP does not use NAT, this callout continues to function as expected.