diff options
7 files changed, 223 insertions, 491 deletions
diff --git a/adapters/mso-catalog-db-adapter/src/main/resources/db/migration/R__MacroData.sql b/adapters/mso-catalog-db-adapter/src/main/resources/db/migration/R__MacroData.sql index b70d409cd8..33293afa10 100644 --- a/adapters/mso-catalog-db-adapter/src/main/resources/db/migration/R__MacroData.sql +++ b/adapters/mso-catalog-db-adapter/src/main/resources/db/migration/R__MacroData.sql @@ -632,7 +632,17 @@ VALUES ('VOLUME_GROUP', 'PENDING', 'DELETE', 'SILENT_SUCCESS'), ('VF_MODULE', 'PENDING', 'DELETE', 'FAIL'), -('NETWORK', 'PENDING', 'DELETE', 'FAIL'); +('NETWORK', 'PENDING', 'DELETE', 'FAIL'), + +('VNF', 'CONFIGURED', 'ACTIVATE', 'CONTINUE'), +('VNF', 'CONFIGURED', 'UNASSIGN', 'CONTINUE'), +('VNF', 'CONFIGURED', 'DESACTIVATE', 'SILENT_SUCCESS'), + +('VNF', 'CONFIGURE', 'UNASSIGN', 'CONTINUE'), +('VNF', 'CONFIGURE', 'DESACTIVATE', 'SILENT_SUCCESS'), + +('VNF', 'CONFIGASSIGNED', 'UNASSIGN', 'CONTINUE'), +('VNF', 'CONFIGASSIGNED', 'DESACTIVATE', 'SILENT_SUCCESS'); UPDATE orchestration_flow_reference SET FLOW_NAME = 'HomingBB' WHERE FLOW_NAME = 'SniroHoming'; diff --git a/adapters/mso-catalog-db-adapter/src/main/resources/db/migration/V9.0.1__AddMissingTransitionStates.sql b/adapters/mso-catalog-db-adapter/src/main/resources/db/migration/V9.0.1__AddMissingTransitionStates.sql deleted file mode 100644 index c0cec5da31..0000000000 --- a/adapters/mso-catalog-db-adapter/src/main/resources/db/migration/V9.0.1__AddMissingTransitionStates.sql +++ /dev/null @@ -1,17 +0,0 @@ -INSERT INTO orchestration_status_state_transition_directive(RESOURCE_TYPE, ORCHESTRATION_STATUS, TARGET_ACTION, FLOW_DIRECTIVE) VALUES -('VNF', 'CONFIGASSIGNED', 'DEACTIVATE', 'SILENT_SUCCESS') ON DUPLICATE KEY UPDATE FLOW_DIRECTIVE = 'SILENT_SUCCES'; - -INSERT INTO orchestration_status_state_transition_directive(RESOURCE_TYPE, ORCHESTRATION_STATUS, TARGET_ACTION, FLOW_DIRECTIVE) VALUES -('VNF', 'CONFIGASSIGNED', 'UNASSIGN', 'CONTINUE') ON DUPLICATE KEY UPDATE FLOW_DIRECTIVE = 'CONTINUE'; - -INSERT INTO orchestration_status_state_transition_directive(RESOURCE_TYPE, ORCHESTRATION_STATUS, TARGET_ACTION, FLOW_DIRECTIVE) VALUES -('VNF', 'CONFIGURE', 'DEACTIVATE', 'SILENT_SUCCESS') ON DUPLICATE KEY UPDATE FLOW_DIRECTIVE = 'SILENT_SUCCES'; - -INSERT INTO orchestration_status_state_transition_directive(RESOURCE_TYPE, ORCHESTRATION_STATUS, TARGET_ACTION, FLOW_DIRECTIVE) VALUES -('VNF', 'CONFIGURE', 'UNASSIGN', 'CONTINUE') ON DUPLICATE KEY UPDATE FLOW_DIRECTIVE = 'CONTINUE'; - -INSERT INTO orchestration_status_state_transition_directive(RESOURCE_TYPE, ORCHESTRATION_STATUS, TARGET_ACTION, FLOW_DIRECTIVE) VALUES -('VNF', 'CONFIGURED', 'UNASSIGN', 'CONTINUE') ON DUPLICATE KEY UPDATE FLOW_DIRECTIVE = 'CONTINUE'; - -INSERT INTO orchestration_status_state_transition_directive(RESOURCE_TYPE, ORCHESTRATION_STATUS, TARGET_ACTION, FLOW_DIRECTIVE) VALUES -('VNF', 'CONFIGURED', 'DEACTIVATE', 'SILENT_SUCCESS') ON DUPLICATE KEY UPDATE FLOW_DIRECTIVE = 'SILENT_SUCCES'; diff --git a/adapters/mso-catalog-db-adapter/src/main/resources/db/migration/V9.0__AddConfiguredForVnfOrchestrationStatus.sql b/adapters/mso-catalog-db-adapter/src/main/resources/db/migration/V9.0__AddConfiguredForVnfOrchestrationStatus.sql deleted file mode 100644 index 1d26c4c8d9..0000000000 --- a/adapters/mso-catalog-db-adapter/src/main/resources/db/migration/V9.0__AddConfiguredForVnfOrchestrationStatus.sql +++ /dev/null @@ -1,2 +0,0 @@ -INSERT INTO orchestration_status_state_transition_directive(RESOURCE_TYPE, ORCHESTRATION_STATUS, TARGET_ACTION, FLOW_DIRECTIVE) -VALUES ('VNF', 'CONFIGURED', 'ACTIVATE', 'CONTINUE') ON DUPLICATE KEY UPDATE FLOW_DIRECTIVE='CONTINUE'; diff --git a/adapters/mso-openstack-adapters/src/main/java/org/onap/so/adapters/network/MsoNetworkAdapterImpl.java b/adapters/mso-openstack-adapters/src/main/java/org/onap/so/adapters/network/MsoNetworkAdapterImpl.java index 4728effdca..860c747f15 100644 --- a/adapters/mso-openstack-adapters/src/main/java/org/onap/so/adapters/network/MsoNetworkAdapterImpl.java +++ b/adapters/mso-openstack-adapters/src/main/java/org/onap/so/adapters/network/MsoNetworkAdapterImpl.java @@ -81,8 +81,8 @@ import com.fasterxml.jackson.databind.ObjectMapper; targetNamespace = "http://org.onap.so/network") public class MsoNetworkAdapterImpl implements MsoNetworkAdapter { - private static final String AIC3_NW_PROPERTY = "org.onap.so.adapters.network.aic3nw"; - private static final String AIC3_NW = "OS::ContrailV2::VirtualNetwork"; + private static final String OS3_NW_PROPERTY = "org.onap.so.adapters.network.aic3nw"; + private static final String OS3_NW = "OS::ContrailV2::VirtualNetwork"; private static final String VLANS = "vlans"; private static final String PHYSICAL_NETWORK = "physical_network"; private static final String UPDATE_NETWORK_CONTEXT = "UpdateNetwork"; @@ -223,272 +223,203 @@ public class MsoNetworkAdapterImpl implements MsoNetworkAdapter { NetworkResource networkResource = networkCheck(startTime, networkType, modelCustomizationUuid, networkName, physicalNetworkName, vlans, routeTargets, cloudSiteId, cloudSiteOpt.get()); - String mode = networkResource.getOrchestrationMode(); NetworkType neutronNetworkType = NetworkType.valueOf(networkResource.getNeutronNetworkType()); - if (NEUTRON_MODE.equals(mode)) { - - // Use an MsoNeutronUtils for all neutron commands - - // See if the Network already exists (by name) - NetworkInfo netInfo = null; - try { - netInfo = neutron.queryNetwork(networkName, tenantId, cloudSiteId); - } catch (MsoException me) { - logger.error( - "{} {} Exception while querying network {} for CloudSite {} from Tenant {} from OpenStack ", - MessageEnum.RA_QUERY_NETWORK_EXC, ErrorCode.BusinessProcessError.getValue(), networkName, - cloudSiteId, tenantId, me); - me.addContext(CREATE_NETWORK_CONTEXT); - throw new NetworkException(me); - } - - if (netInfo != null) { - // Exists. If that's OK, return success with the network ID. - // Otherwise, return an exception. - if (failIfExists != null && failIfExists) { - String error = String.format("Create Nework: Network %s already exists in %s/%s with ID %s", - networkName, cloudSiteId, tenantId, netInfo.getId()); - logger.error(LoggingAnchor.THREE, MessageEnum.RA_NETWORK_ALREADY_EXIST, - ErrorCode.DataError.getValue(), error); - throw new NetworkException(error, MsoExceptionCategory.USERDATA); - } else { - // Populate the outputs from the existing network. - networkId.value = netInfo.getId(); - neutronNetworkId.value = netInfo.getId(); - rollback.value = networkRollback; // Default rollback - no updates performed - logger.warn("{} {} Found Existing network, status={} for Neutron mode ", - MessageEnum.RA_NETWORK_ALREADY_EXIST, ErrorCode.DataError.getValue(), netInfo.getStatus()); - } - heat.updateResourceStatus(msoRequest.getRequestId(), NETWORK_EXIST_STATUS_MESSAGE); - return; - } + HeatTemplate heatTemplate = networkResource.getHeatTemplate(); + if (heatTemplate == null) { + String error = String.format("Network error - undefined Heat Template. Network Type = %s", networkType); + logger.error(LoggingAnchor.THREE, MessageEnum.RA_PARAM_NOT_FOUND, ErrorCode.DataError.getValue(), error); + throw new NetworkException(error, MsoExceptionCategory.INTERNAL); + } - try { - netInfo = neutron.createNetwork(cloudSiteId, tenantId, neutronNetworkType, networkName, - physicalNetworkName, vlans); - } catch (MsoException me) { - me.addContext(CREATE_NETWORK_CONTEXT); - logger.error("{} {} Create Network: type {} in {}/{}: ", MessageEnum.RA_CREATE_NETWORK_EXC, - ErrorCode.DataError.getValue(), neutronNetworkType, cloudSiteId, tenantId, me); + logger.debug("Got HEAT Template from DB: {}", heatTemplate); - throw new NetworkException(me); - } + // "Fix" the template if it has CR/LF (getting this from Oracle) + String template = heatTemplate.getHeatTemplate(); + template = template.replaceAll("\r\n", "\n"); - // Note: ignoring MsoNetworkAlreadyExists because we already checked. + boolean os3template = false; + String os3nw = OS3_NW; - // If reach this point, network creation is successful. - // Since directly created via Neutron, networkId tracked by MSO is the same - // as the neutron network ID. - networkId.value = netInfo.getId(); - neutronNetworkId.value = netInfo.getId(); + os3nw = environment.getProperty(OS3_NW_PROPERTY, OS3_NW); - networkRollback.setNetworkCreated(true); - networkRollback.setNetworkId(netInfo.getId()); - networkRollback.setNeutronNetworkId(netInfo.getId()); - networkRollback.setNetworkType(networkType); + if (template.contains(os3nw)) + os3template = true; - logger.debug("Network {} created, id = {}", networkName, netInfo.getId()); - } else if ("HEAT".equals(mode)) { + // First, look up to see if the Network already exists (by name). + // For HEAT orchestration of networks, the stack name will always match the network name + StackInfo heatStack = null; + try { + heatStack = heat.queryStack(cloudSiteId, CLOUD_OWNER, tenantId, networkName); + } catch (MsoException me) { + me.addContext(CREATE_NETWORK_CONTEXT); + logger.error("{} {} Create Network (heat): query network {} in {}/{}: ", MessageEnum.RA_QUERY_NETWORK_EXC, + ErrorCode.DataError.getValue(), networkName, cloudSiteId, tenantId, me); + throw new NetworkException(me); + } - HeatTemplate heatTemplate = networkResource.getHeatTemplate(); - if (heatTemplate == null) { - String error = String.format("Network error - undefined Heat Template. Network Type = %s", networkType); - logger.error(LoggingAnchor.THREE, MessageEnum.RA_PARAM_NOT_FOUND, ErrorCode.DataError.getValue(), + if (heatStack != null && (heatStack.getStatus() != HeatStatus.NOTFOUND)) { + // Stack exists. Return success or error depending on input directive + if (failIfExists != null && failIfExists) { + String error = String.format("CreateNetwork: Stack %s already exists in %s/%s as %s", networkName, + cloudSiteId, tenantId, heatStack.getCanonicalName()); + logger.error(LoggingAnchor.THREE, MessageEnum.RA_NETWORK_ALREADY_EXIST, ErrorCode.DataError.getValue(), error); - throw new NetworkException(error, MsoExceptionCategory.INTERNAL); - } - - logger.debug("Got HEAT Template from DB: {}", heatTemplate); - - // "Fix" the template if it has CR/LF (getting this from Oracle) - String template = heatTemplate.getHeatTemplate(); - template = template.replaceAll("\r\n", "\n"); - - boolean aic3template = false; - String aic3nw = AIC3_NW; - - aic3nw = environment.getProperty(AIC3_NW_PROPERTY, AIC3_NW); - - if (template.contains(aic3nw)) - aic3template = true; - - // First, look up to see if the Network already exists (by name). - // For HEAT orchestration of networks, the stack name will always match the network name - StackInfo heatStack = null; - try { - heatStack = heat.queryStack(cloudSiteId, CLOUD_OWNER, tenantId, networkName); - } catch (MsoException me) { - me.addContext(CREATE_NETWORK_CONTEXT); - logger.error("{} {} Create Network (heat): query network {} in {}/{}: ", - MessageEnum.RA_QUERY_NETWORK_EXC, ErrorCode.DataError.getValue(), networkName, cloudSiteId, - tenantId, me); - throw new NetworkException(me); - } - - if (heatStack != null && (heatStack.getStatus() != HeatStatus.NOTFOUND)) { - // Stack exists. Return success or error depending on input directive - if (failIfExists != null && failIfExists) { - String error = String.format("CreateNetwork: Stack %s already exists in %s/%s as %s", networkName, - cloudSiteId, tenantId, heatStack.getCanonicalName()); - logger.error(LoggingAnchor.THREE, MessageEnum.RA_NETWORK_ALREADY_EXIST, - ErrorCode.DataError.getValue(), error); - throw new NetworkException(error, MsoExceptionCategory.USERDATA); - } else { - // Populate the outputs from the existing stack. - networkId.value = heatStack.getCanonicalName(); - Map<String, String> sMap = new HashMap<>(); - if (heatStack.getOutputs() != null) { - neutronNetworkId.value = (String) heatStack.getOutputs().get(NETWORK_ID); - rollback.value = networkRollback; // Default rollback - no updates performed - if (aic3template) { - networkFqdn.value = (String) heatStack.getOutputs().get(NETWORK_FQDN); - } - Map<String, Object> outputs = heatStack.getOutputs(); - - for (Map.Entry<String, Object> entry : outputs.entrySet()) { - String key = entry.getKey(); - if (key != null && key.startsWith("subnet")) { - if (aic3template) // one subnet_id output - { - Map<String, String> map = getSubnetUUId(key, outputs, subnets); - sMap.putAll(map); - } else // multiples subnet_%aaid% outputs - { - String subnetUUId = (String) outputs.get(key); - sMap.put(key.substring("subnet_id_".length()), subnetUUId); - } + throw new NetworkException(error, MsoExceptionCategory.USERDATA); + } else { + // Populate the outputs from the existing stack. + networkId.value = heatStack.getCanonicalName(); + Map<String, String> sMap = new HashMap<>(); + if (heatStack.getOutputs() != null) { + neutronNetworkId.value = (String) heatStack.getOutputs().get(NETWORK_ID); + rollback.value = networkRollback; // Default rollback - no updates performed + if (os3template) { + networkFqdn.value = (String) heatStack.getOutputs().get(NETWORK_FQDN); + } + Map<String, Object> outputs = heatStack.getOutputs(); + + for (Map.Entry<String, Object> entry : outputs.entrySet()) { + String key = entry.getKey(); + if (key != null && key.startsWith("subnet")) { + if (os3template) // one subnet_id output + { + Map<String, String> map = getSubnetUUId(key, outputs, subnets); + sMap.putAll(map); + } else // multiples subnet_%aaid% outputs + { + String subnetUUId = (String) outputs.get(key); + sMap.put(key.substring("subnet_id_".length()), subnetUUId); } } } - subnetIdMap.value = sMap; - logger.warn("{} {} Found Existing network stack, status={} networkName={} for {}/{}", - MessageEnum.RA_NETWORK_ALREADY_EXIST, ErrorCode.DataError.getValue(), heatStack.getStatus(), - networkName, cloudSiteId, tenantId); } - heat.updateResourceStatus(msoRequest.getRequestId(), NETWORK_EXIST_STATUS_MESSAGE); - return; + subnetIdMap.value = sMap; + logger.warn("{} {} Found Existing network stack, status={} networkName={} for {}/{}", + MessageEnum.RA_NETWORK_ALREADY_EXIST, ErrorCode.DataError.getValue(), heatStack.getStatus(), + networkName, cloudSiteId, tenantId); } + heat.updateResourceStatus(msoRequest.getRequestId(), NETWORK_EXIST_STATUS_MESSAGE); + return; + } - // Ready to deploy the new Network - // Build the common set of HEAT template parameters - Map<String, Object> stackParams = populateNetworkParams(neutronNetworkType, networkName, - physicalNetworkName, vlans, routeTargets, shared, external, aic3template); - - // Validate (and update) the input parameters against the DB definition - // Shouldn't happen unless DB config is wrong, since all networks use same inputs - // and inputs were already validated. - try { - stackParams = heat.validateStackParams(stackParams, heatTemplate); - } catch (IllegalArgumentException e) { - String error = "Create Network: Configuration Error: " + e.getMessage(); - logger.error(LoggingAnchor.THREE, MessageEnum.RA_CONFIG_EXC, ErrorCode.DataError.getValue(), error, e); - // Input parameters were not valid - throw new NetworkException(error, MsoExceptionCategory.INTERNAL); - } + // Ready to deploy the new Network + // Build the common set of HEAT template parameters + Map<String, Object> stackParams = populateNetworkParams(neutronNetworkType, networkName, physicalNetworkName, + vlans, routeTargets, shared, external, os3template); - if (subnets != null) { - try { - if (aic3template) { - template = mergeSubnetsAIC3(template, subnets, stackParams); - } else { - template = mergeSubnets(template, subnets); - } - } catch (MsoException me) { - me.addContext(CREATE_NETWORK_CONTEXT); - logger.error("{} {} Exception Create Network, merging subnets for network (heat) type {} in {}/{} ", - MessageEnum.RA_CREATE_NETWORK_EXC, ErrorCode.DataError.getValue(), - neutronNetworkType.toString(), cloudSiteId, tenantId, me); - throw new NetworkException(me); - } - } + // Validate (and update) the input parameters against the DB definition + // Shouldn't happen unless DB config is wrong, since all networks use same inputs + // and inputs were already validated. + try { + stackParams = heat.validateStackParams(stackParams, heatTemplate); + } catch (IllegalArgumentException e) { + String error = "Create Network: Configuration Error: " + e.getMessage(); + logger.error(LoggingAnchor.THREE, MessageEnum.RA_CONFIG_EXC, ErrorCode.DataError.getValue(), error, e); + // Input parameters were not valid + throw new NetworkException(error, MsoExceptionCategory.INTERNAL); + } - if (policyFqdns != null && !policyFqdns.isEmpty() && aic3template) { - try { - mergePolicyRefs(policyFqdns, stackParams); - } catch (MsoException me) { - me.addContext(CREATE_NETWORK_CONTEXT); - logger.error("{} {} Exception Create Network, merging policyRefs type {} in {}/{} ", - MessageEnum.RA_CREATE_NETWORK_EXC, ErrorCode.DataError.getValue(), - neutronNetworkType.toString(), cloudSiteId, tenantId, me); - throw new NetworkException(me); + if (subnets != null) { + try { + if (os3template) { + template = mergeSubnetsAIC3(template, subnets, stackParams); + } else { + template = mergeSubnets(template, subnets); } + } catch (MsoException me) { + me.addContext(CREATE_NETWORK_CONTEXT); + logger.error("{} {} Exception Create Network, merging subnets for network (heat) type {} in {}/{} ", + MessageEnum.RA_CREATE_NETWORK_EXC, ErrorCode.DataError.getValue(), + neutronNetworkType.toString(), cloudSiteId, tenantId, me); + throw new NetworkException(me); } + } - if (routeTableFqdns != null && !routeTableFqdns.isEmpty() && aic3template) { - try { - mergeRouteTableRefs(routeTableFqdns, stackParams); - } catch (MsoException me) { - me.addContext(CREATE_NETWORK_CONTEXT); - logger.error("{} {} Exception Create Network, merging routeTableRefs type {} in {}/{} ", - MessageEnum.RA_CREATE_NETWORK_EXC, ErrorCode.DataError.getValue(), - neutronNetworkType.toString(), cloudSiteId, tenantId, me); - throw new NetworkException(me); - } + if (policyFqdns != null && !policyFqdns.isEmpty() && os3template) { + try { + mergePolicyRefs(policyFqdns, stackParams); + } catch (MsoException me) { + me.addContext(CREATE_NETWORK_CONTEXT); + logger.error("{} {} Exception Create Network, merging policyRefs type {} in {}/{} ", + MessageEnum.RA_CREATE_NETWORK_EXC, ErrorCode.DataError.getValue(), + neutronNetworkType.toString(), cloudSiteId, tenantId, me); + throw new NetworkException(me); } + } - // Deploy the network stack - // Ignore MsoStackAlreadyExists exception because we already checked. + if (routeTableFqdns != null && !routeTableFqdns.isEmpty() && os3template) { try { - if (backout == null) - backout = true; - heatStack = heat.createStack(cloudSiteId, CLOUD_OWNER, tenantId, networkName, null, template, - stackParams, true, heatTemplate.getTimeoutMinutes(), null, null, null, backout.booleanValue(), - failIfExists); + mergeRouteTableRefs(routeTableFqdns, stackParams); } catch (MsoException me) { me.addContext(CREATE_NETWORK_CONTEXT); - logger.error("{} {} Exception creating network type {} in {}/{} ", MessageEnum.RA_CREATE_NETWORK_EXC, - ErrorCode.DataError.getValue(), networkName, cloudSiteId, tenantId, me); + logger.error("{} {} Exception Create Network, merging routeTableRefs type {} in {}/{} ", + MessageEnum.RA_CREATE_NETWORK_EXC, ErrorCode.DataError.getValue(), + neutronNetworkType.toString(), cloudSiteId, tenantId, me); throw new NetworkException(me); } + } - // Reach this point if createStack is successful. + // Deploy the network stack + // Ignore MsoStackAlreadyExists exception because we already checked. + try { + if (backout == null) + backout = true; + heatStack = heat.createStack(cloudSiteId, CLOUD_OWNER, tenantId, networkName, null, template, stackParams, + true, heatTemplate.getTimeoutMinutes(), null, null, null, backout.booleanValue(), failIfExists); + } catch (MsoException me) { + me.addContext(CREATE_NETWORK_CONTEXT); + logger.error("{} {} Exception creating network type {} in {}/{} ", MessageEnum.RA_CREATE_NETWORK_EXC, + ErrorCode.DataError.getValue(), networkName, cloudSiteId, tenantId, me); + throw new NetworkException(me); + } - // For Heat-based orchestration, the MSO-tracked network ID is the heat stack, - // and the neutronNetworkId is the network UUID returned in stack outputs. - networkId.value = heatStack.getCanonicalName(); - if (heatStack.getOutputs() != null) { - neutronNetworkId.value = (String) heatStack.getOutputs().get(NETWORK_ID); - if (aic3template) { - networkFqdn.value = (String) heatStack.getOutputs().get(NETWORK_FQDN); - } + // Reach this point if createStack is successful. + + // For Heat-based orchestration, the MSO-tracked network ID is the heat stack, + // and the neutronNetworkId is the network UUID returned in stack outputs. + networkId.value = heatStack.getCanonicalName(); + if (heatStack.getOutputs() != null) { + neutronNetworkId.value = (String) heatStack.getOutputs().get(NETWORK_ID); + if (os3template) { + networkFqdn.value = (String) heatStack.getOutputs().get(NETWORK_FQDN); } - Map<String, Object> outputs = heatStack.getOutputs(); - Map<String, String> sMap = new HashMap<>(); - if (outputs != null) { - for (Map.Entry<String, Object> entry : outputs.entrySet()) { - String key = entry.getKey(); - if (key != null && key.startsWith("subnet")) { - if (aic3template) // one subnet output expected - { - Map<String, String> map = getSubnetUUId(key, outputs, subnets); - sMap.putAll(map); - } else // multiples subnet_%aaid% outputs allowed - { - String subnetUUId = (String) outputs.get(key); - sMap.put(key.substring("subnet_id_".length()), subnetUUId); - } + } + Map<String, Object> outputs = heatStack.getOutputs(); + Map<String, String> sMap = new HashMap<>(); + if (outputs != null) { + for (Map.Entry<String, Object> entry : outputs.entrySet()) { + String key = entry.getKey(); + if (key != null && key.startsWith("subnet")) { + if (os3template) // one subnet output expected + { + Map<String, String> map = getSubnetUUId(key, outputs, subnets); + sMap.putAll(map); + } else // multiples subnet_%aaid% outputs allowed + { + String subnetUUId = (String) outputs.get(key); + sMap.put(key.substring("subnet_id_".length()), subnetUUId); } } - networkRollback.setNeutronNetworkId((String) outputs.get(NETWORK_ID)); } - subnetIdMap.value = sMap; - - rollback.value = networkRollback; - // Populate remaining rollback info and response parameters. - networkRollback.setNetworkStackId(heatStack.getCanonicalName()); - networkRollback.setNetworkCreated(true); - networkRollback.setNetworkType(networkType); + networkRollback.setNeutronNetworkId((String) outputs.get(NETWORK_ID)); + } + subnetIdMap.value = sMap; - try { - heat.updateResourceStatus(msoRequest.getRequestId(), NETWORK_CREATED_STATUS_MESSAGE); - } catch (Exception e) { - logger.warn("Exception while updating infra active request", e); - } + rollback.value = networkRollback; + // Populate remaining rollback info and response parameters. + networkRollback.setNetworkStackId(heatStack.getCanonicalName()); + networkRollback.setNetworkCreated(true); + networkRollback.setNetworkType(networkType); - logger.debug("Network {} successfully created via HEAT", networkName); + try { + heat.updateResourceStatus(msoRequest.getRequestId(), NETWORK_CREATED_STATUS_MESSAGE); + } catch (Exception e) { + logger.warn("Exception while updating infra active request", e); } + logger.debug("Network {} successfully created via HEAT", networkName); + + return; } @@ -674,17 +605,17 @@ public class MsoNetworkAdapterImpl implements MsoNetworkAdapter { String template = heatTemplate.getHeatTemplate(); template = template.replaceAll("\r\n", "\n"); - boolean aic3template = false; - String aic3nw = AIC3_NW; + boolean os3template = false; + String os3nw = OS3_NW; - aic3nw = environment.getProperty(AIC3_NW_PROPERTY, AIC3_NW); + os3nw = environment.getProperty(OS3_NW_PROPERTY, OS3_NW); - if (template.contains(aic3nw)) - aic3template = true; + if (template.contains(os3nw)) + os3template = true; // Build the common set of HEAT template parameters Map<String, Object> stackParams = populateNetworkParams(neutronNetworkType, networkName, - physicalNetworkName, vlans, routeTargets, shared, external, aic3template); + physicalNetworkName, vlans, routeTargets, shared, external, os3template); // Validate (and update) the input parameters against the DB definition // Shouldn't happen unless DB config is wrong, since all networks use same inputs @@ -698,7 +629,7 @@ public class MsoNetworkAdapterImpl implements MsoNetworkAdapter { if (subnets != null) { try { - if (aic3template) { + if (os3template) { template = mergeSubnetsAIC3(template, subnets, stackParams); } else { template = mergeSubnets(template, subnets); @@ -712,7 +643,7 @@ public class MsoNetworkAdapterImpl implements MsoNetworkAdapter { } } - if (policyFqdns != null && aic3template) { + if (policyFqdns != null && os3template) { try { mergePolicyRefs(policyFqdns, stackParams); } catch (MsoException me) { @@ -724,7 +655,7 @@ public class MsoNetworkAdapterImpl implements MsoNetworkAdapter { } } - if (routeTableFqdns != null && !routeTableFqdns.isEmpty() && aic3template) { + if (routeTableFqdns != null && !routeTableFqdns.isEmpty() && os3template) { try { mergeRouteTableRefs(routeTableFqdns, stackParams); } catch (MsoException me) { @@ -754,7 +685,7 @@ public class MsoNetworkAdapterImpl implements MsoNetworkAdapter { for (Map.Entry<String, Object> entry : outputs.entrySet()) { String key = entry.getKey(); if (key != null && key.startsWith("subnet")) { - if (aic3template) // one subnet output expected + if (os3template) // one subnet output expected { Map<String, String> map = getSubnetUUId(key, outputs, subnets); sMap.putAll(map); @@ -837,14 +768,14 @@ public class MsoNetworkAdapterImpl implements MsoNetworkAdapter { throw new NetworkException(error, MsoExceptionCategory.INTERNAL); } - MavenLikeVersioning aicV = new MavenLikeVersioning(); - aicV.setVersion(cloudSite.getCloudVersion()); - if ((aicV.isMoreRecentThan(networkResource.getAicVersionMin()) - || aicV.isTheSameVersion(networkResource.getAicVersionMin())) // aic + MavenLikeVersioning osV = new MavenLikeVersioning(); + osV.setVersion(cloudSite.getCloudVersion()); + if ((osV.isMoreRecentThan(networkResource.getAicVersionMin()) + || osV.isTheSameVersion(networkResource.getAicVersionMin())) // os // >= // min - && (aicV.isTheSameVersion(networkResource.getAicVersionMax()) - || !(aicV.isMoreRecentThan(networkResource.getAicVersionMax())))) // aic <= max + && (osV.isTheSameVersion(networkResource.getAicVersionMax()) + || !(osV.isMoreRecentThan(networkResource.getAicVersionMax())))) // os <= max { logger.debug("Network Type:{} VersionMin:{} VersionMax:{} supported on Cloud:{} with AIC_Version:{}", networkType, networkResource.getAicVersionMin(), networkResource.getAicVersionMax(), cloudSiteId, @@ -921,7 +852,6 @@ public class MsoNetworkAdapterImpl implements MsoNetworkAdapter { // Use MsoNeutronUtils for all NEUTRON commands - String mode; String neutronId = null; // Try Heat first, since networks may be named the same as the Heat stack StackInfo heatStack = null; @@ -939,7 +869,6 @@ public class MsoNetworkAdapterImpl implements MsoNetworkAdapter { // Found it. Get the neutronNetworkId for further query Map<String, String> sMap = new HashMap<>(); Map<String, Object> outputs = heatStack.getOutputs(); - mode = "HEAT"; if (outputs != null) { neutronId = (String) outputs.get(NETWORK_ID); @@ -957,10 +886,6 @@ public class MsoNetworkAdapterImpl implements MsoNetworkAdapter { } } subnetIdMap.value = sMap; - } else { - // Input ID was not a Heat stack ID. Try it directly in Neutron - neutronId = networkNameOrId; - mode = NEUTRON_MODE; } // Query directly against the Neutron Network for the details @@ -971,7 +896,7 @@ public class MsoNetworkAdapterImpl implements MsoNetworkAdapter { if (netInfo != null) { // Found. Populate the output elements networkExists.value = Boolean.TRUE; - if ("HEAT".equals(mode) && heatStack != null) { + if (heatStack != null) { networkId.value = heatStack.getCanonicalName(); } else { networkId.value = netInfo.getId(); @@ -981,8 +906,8 @@ public class MsoNetworkAdapterImpl implements MsoNetworkAdapter { if (vlans != null) vlans.value = netInfo.getVlans(); - logger.debug("Network {} found({}), ID = {}{}", networkNameOrId, mode, networkId.value, - ("HEAT".equals(mode) ? ",NeutronId = " + neutronNetworkId.value : "")); + logger.debug("Network {}, ID = {}{}", networkNameOrId, networkId.value, + (",NeutronId = " + neutronNetworkId.value)); } else { // Not found. Populate the status fields, leave the rest null networkExists.value = Boolean.FALSE; @@ -1043,10 +968,8 @@ public class MsoNetworkAdapterImpl implements MsoNetworkAdapter { } int timeoutMinutes = 118; - String mode = ""; if (networkResource != null) { logger.debug(LOG_DEBUG_MSG, networkResource.toString()); - mode = networkResource.getOrchestrationMode(); networkResource.getHeatTemplate().getTimeoutMinutes(); HeatTemplate heat = networkResource.getHeatTemplate(); if (heat != null && heat.getTimeoutMinutes() != null) { @@ -1056,27 +979,16 @@ public class MsoNetworkAdapterImpl implements MsoNetworkAdapter { } } - if (NEUTRON_MODE.equals(mode)) { - try { - boolean deleted = neutron.deleteNetwork(networkId, tenantId, cloudSiteId); - networkDeleted.value = deleted; - } catch (MsoException me) { - me.addContext("DeleteNetwork"); - logger.error("{} {} Delete Network (neutron): {} in {}/{} ", MessageEnum.RA_DELETE_NETWORK_EXC, - ErrorCode.DataError.getValue(), networkId, cloudSiteId, tenantId, me); - throw new NetworkException(me); - } - } else { - try { - StackInfo stack = heat.deleteStack(tenantId, CLOUD_OWNER, cloudSiteId, networkId, true, timeoutMinutes); - networkDeleted.value = stack.isOperationPerformed(); - } catch (MsoException me) { - me.addContext("DeleteNetwork"); - logger.error("{} {} Delete Network (heat): {} in {}/{} ", MessageEnum.RA_DELETE_NETWORK_EXC, - ErrorCode.DataError.getValue(), networkId, cloudSiteId, tenantId, me); - throw new NetworkException(me); - } + try { + StackInfo stack = heat.deleteStack(tenantId, CLOUD_OWNER, cloudSiteId, networkId, true, timeoutMinutes); + networkDeleted.value = stack.isOperationPerformed(); + } catch (MsoException me) { + me.addContext("DeleteNetwork"); + logger.error("{} {} Delete Network (heat): {} in {}/{} ", MessageEnum.RA_DELETE_NETWORK_EXC, + ErrorCode.DataError.getValue(), networkId, cloudSiteId, tenantId, me); + throw new NetworkException(me); } + try { heat.updateResourceStatus(msoRequest.getRequestId(), networkDeleted.value ? NETWORK_DELETED_STATUS_MESSAGE : NETWORK_NOT_EXIST_STATUS_MESSAGE); @@ -1104,48 +1016,20 @@ public class MsoNetworkAdapterImpl implements MsoNetworkAdapter { String cloudSiteId = rollback.getCloudId(); String tenantId = rollback.getTenantId(); String networkId = rollback.getNetworkStackId(); - String networkType = rollback.getNetworkType(); - String modelCustomizationUuid = rollback.getModelCustomizationUuid(); logger.debug("*** ROLLBACK Network {} in {}/{}", networkId, cloudSiteId, tenantId); - // Retrieve the Network Resource definition - NetworkResource networkResource = null; - if (commonUtils.isNullOrEmpty(modelCustomizationUuid)) { - networkResource = networkCustomRepo.findOneByNetworkType(networkType).getNetworkResource(); - } else { - networkResource = - networkCustomRepo.findOneByModelCustomizationUUID(modelCustomizationUuid).getNetworkResource(); - } - String mode = ""; - if (networkResource != null) { - - logger.debug(LOG_DEBUG_MSG, networkResource); - - mode = networkResource.getOrchestrationMode(); - } if (rollback.getNetworkCreated()) { - if (NEUTRON_MODE.equals(mode)) { - try { - neutron.deleteNetwork(networkId, tenantId, cloudSiteId); - } catch (MsoException me) { - me.addContext("RollbackNetwork"); - logger.error("{} {} Exception - Rollback Network (neutron): {} in {}/{} ", - MessageEnum.RA_DELETE_NETWORK_EXC, ErrorCode.BusinessProcessError.getValue(), networkId, - cloudSiteId, tenantId, me); - throw new NetworkException(me); - } - } else { - try { - heat.deleteStack(tenantId, CLOUD_OWNER, cloudSiteId, networkId, true, 120); - } catch (MsoException me) { - me.addContext("RollbackNetwork"); - logger.error("{} {} Exception - Rollback Network (heat): {} in {}/{} ", - MessageEnum.RA_DELETE_NETWORK_EXC, ErrorCode.BusinessProcessError.getValue(), networkId, - cloudSiteId, tenantId, me); - throw new NetworkException(me); - } + try { + heat.deleteStack(tenantId, CLOUD_OWNER, cloudSiteId, networkId, true, 120); + } catch (MsoException me) { + me.addContext("RollbackNetwork"); + logger.error("{} {} Exception - Rollback Network (heat): {} in {}/{} ", + MessageEnum.RA_DELETE_NETWORK_EXC, ErrorCode.BusinessProcessError.getValue(), networkId, + cloudSiteId, tenantId, me); + throw new NetworkException(me); } + } } @@ -1173,7 +1057,7 @@ public class MsoNetworkAdapterImpl implements MsoNetworkAdapter { private Map<String, Object> populateNetworkParams(NetworkType neutronNetworkType, String networkName, String physicalNetwork, List<Integer> vlans, List<RouteTarget> routeTargets, String shared, String external, - boolean aic3template) { + boolean os3template) { // Build the common set of HEAT template parameters Map<String, Object> stackParams = new HashMap<>(); stackParams.put("network_name", networkName); @@ -1227,14 +1111,14 @@ public class MsoNetworkAdapterImpl implements MsoNetworkAdapter { if ("IMPORT".equalsIgnoreCase(role)) { sep = rtImport.isEmpty() ? "" : ","; - rtImport = aic3template ? rtImport + sep + "target:" + rtValue : rtImport + sep + rtValue; + rtImport = os3template ? rtImport + sep + "target:" + rtValue : rtImport + sep + rtValue; } else if ("EXPORT".equalsIgnoreCase(role)) { sep = rtExport.isEmpty() ? "" : ","; - rtExport = aic3template ? rtExport + sep + "target:" + rtValue : rtExport + sep + rtValue; + rtExport = os3template ? rtExport + sep + "target:" + rtValue : rtExport + sep + rtValue; } else // covers BOTH, empty etc { sep = rtGlobal.isEmpty() ? "" : ","; - rtGlobal = aic3template ? rtGlobal + sep + "target:" + rtValue : rtGlobal + sep + rtValue; + rtGlobal = os3template ? rtGlobal + sep + "target:" + rtValue : rtGlobal + sep + rtValue; } } diff --git a/adapters/mso-openstack-adapters/src/main/java/org/onap/so/heatbridge/helpers/AaiHelper.java b/adapters/mso-openstack-adapters/src/main/java/org/onap/so/heatbridge/helpers/AaiHelper.java index c578b29664..adcde92917 100644 --- a/adapters/mso-openstack-adapters/src/main/java/org/onap/so/heatbridge/helpers/AaiHelper.java +++ b/adapters/mso-openstack-adapters/src/main/java/org/onap/so/heatbridge/helpers/AaiHelper.java @@ -148,10 +148,16 @@ public class AaiHelper { public Pserver buildPserver(final Server server) { Pserver pserver = new Pserver(); pserver.setInMaint(false); - pserver.setPserverId(server.getId()); pserver.setHostname(server.getHypervisorHostname()); - pserver.setPserverName2(server.getHost()); - pserver.setProvStatus(server.getStatus().value()); + if (server.getId() != null) { + pserver.setPserverId(server.getId()); + } + if (server.getHost() != null) { + pserver.setPserverName2(server.getHost()); + } + if (server.getStatus() != null && server.getStatus().value() != null) { + pserver.setProvStatus(server.getStatus().value()); + } return pserver; } diff --git a/adapters/mso-openstack-adapters/src/test/java/org/onap/so/adapters/network/MSONetworkAdapterImplTest.java b/adapters/mso-openstack-adapters/src/test/java/org/onap/so/adapters/network/MSONetworkAdapterImplTest.java index 284067a766..88c6992a0a 100644 --- a/adapters/mso-openstack-adapters/src/test/java/org/onap/so/adapters/network/MSONetworkAdapterImplTest.java +++ b/adapters/mso-openstack-adapters/src/test/java/org/onap/so/adapters/network/MSONetworkAdapterImplTest.java @@ -63,86 +63,6 @@ public class MSONetworkAdapterImplTest extends BaseRestTestUtils { public static final String NETWORK_NAME = "vUSP-23804-T-01-dpa2b_EVUSP-CORE-VIF-TSIG0_net_0"; - - @Test - public void createNetworkByModelNameNeutronModeGetNetworkException() throws IOException { - mockOpenStackResponseAccess(wireMockServer, wireMockPort); - - mockOpenstackGet(wireMockServer, "/mockPublicUrl/v2.0/networks", HttpStatus.SC_INTERNAL_SERVER_ERROR); - - String uri = "/services/NetworkAdapter"; - headers.set("X-ECOMP-RequestID", "123456789456127"); - ResponseEntity<String> response = - sendXMLRequest(inputStream("/CreateNetwork_NEUTRON_Mode.xml"), uri, HttpMethod.POST); - assertEquals(Response.Status.INTERNAL_SERVER_ERROR.getStatusCode(), response.getStatusCode().value()); - } - - @Test - public void createNetworkByModelNameNeutronModeCreateNetworkException() throws IOException { - - mockOpenStackResponseAccess(wireMockServer, wireMockPort); - - mockOpenStackGetNeutronNetwork_404(wireMockServer, "dvspg-VCE_VPE-mtjnj40avbc"); - - mockOpenStackGetAllNeutronNetworks_404(wireMockServer); - - mockOpenstackPost(wireMockServer, "/mockPublicUrl/v2.0/networks", HttpStatus.SC_INTERNAL_SERVER_ERROR); - - String uri = "/services/NetworkAdapter"; - headers.set("X-ECOMP-RequestID", "123456789456127"); - ResponseEntity<String> response = - sendXMLRequest(inputStream("/CreateNetwork_NEUTRON_Mode.xml"), uri, HttpMethod.POST); - assertEquals(Response.Status.INTERNAL_SERVER_ERROR.getStatusCode(), response.getStatusCode().value()); - } - - @Test - public void createNetworkByModelNameNeutronMode() throws IOException { - - mockOpenStackResponseAccess(wireMockServer, wireMockPort); - - mockOpenStackGetNeutronNetwork_404(wireMockServer, "dvspg-VCE_VPE-mtjnj40avbc"); - - mockOpenStackGetAllNeutronNetworks_404(wireMockServer); - - mockOpenStackPostNeutronNetwork_200(wireMockServer, "OpenstackCreateNeutronNetworkResponse.json"); - - String uri = "/services/NetworkAdapter"; - headers.set("X-ECOMP-RequestID", "123456789456127"); - ResponseEntity<String> response = - sendXMLRequest(inputStream("/CreateNetwork_NEUTRON_Mode.xml"), uri, HttpMethod.POST); - assertEquals(Response.Status.OK.getStatusCode(), response.getStatusCode().value()); - } - - @Test - public void createNetworkByModelNameAlreadyExistNeutronMode() throws IOException { - - mockUpdateRequestDb(wireMockServer, "9733c8d1-2668-4e5f-8b51-2cacc9b662c0"); - - mockOpenStackResponseAccess(wireMockServer, wireMockPort); - - mockOpenStackGetAllNeutronNetworks_200(wireMockServer, "OpenstackGetNeutronNetworks.json"); - - String uri = "/services/NetworkAdapter"; - headers.set("X-ECOMP-RequestID", "123456789456127"); - ResponseEntity<String> response = - sendXMLRequest(inputStream("/CreateNetwork_NEUTRON_Mode.xml"), uri, HttpMethod.POST); - assertEquals(Response.Status.OK.getStatusCode(), response.getStatusCode().value()); - } - - @Test - public void createNetworkByModelNameAlreadyExistNeutronModeFailIfExistTrue() throws IOException { - - mockOpenStackResponseAccess(wireMockServer, wireMockPort); - - mockOpenStackGetAllNeutronNetworks_200(wireMockServer, "OpenstackGetNeutronNetworks.json"); - - String uri = "/services/NetworkAdapter"; - headers.set("X-ECOMP-RequestID", "123456789456127"); - ResponseEntity<String> response = - sendXMLRequest(inputStream("/CreateNetwork_NEUTRON_Mode_Fail_If_Exist_True.xml"), uri, HttpMethod.POST); - assertEquals(Response.Status.INTERNAL_SERVER_ERROR.getStatusCode(), response.getStatusCode().value()); - } - @Test public void createNetworkByModelNameHeatMode() throws IOException { @@ -300,61 +220,6 @@ public class MSONetworkAdapterImplTest extends BaseRestTestUtils { assertEquals(Response.Status.INTERNAL_SERVER_ERROR.getStatusCode(), response.getStatusCode().value()); } - - @Test - public void deleteNetworkNeureonMode() throws IOException { - - mockUpdateRequestDb(wireMockServer, "5a29d907-b8c7-47bf-85f3-3940c0cce0f7"); - - mockOpenStackResponseAccess(wireMockServer, wireMockPort); - - mockOpenStackGetNeutronNetwork(wireMockServer, "GetNeutronNetwork.json", NETWORK_ID, HttpStatus.SC_OK); - - mockOpenStackDeleteNeutronNetwork(wireMockServer, NETWORK_ID, HttpStatus.SC_OK); - - String uri = "/services/NetworkAdapter"; - headers.set("X-ECOMP-RequestID", "123456789456127"); - ResponseEntity<String> response = - sendXMLRequest(inputStream("/DeleteNetwork.xml").replace("CONTRAIL30_BASIC", "CONTRAIL31_GNDIRECT"), - uri, HttpMethod.POST); - assertEquals(Response.Status.OK.getStatusCode(), response.getStatusCode().value()); - } - - @Test - public void deleteNetworkNeutronModeDeleteStackException() throws IOException { - - mockOpenStackResponseAccess(wireMockServer, wireMockPort); - - mockOpenStackGetNeutronNetwork(wireMockServer, "GetNeutronNetwork.json", NETWORK_ID, HttpStatus.SC_OK); - - mockOpenStackDeleteNeutronNetwork(wireMockServer, NETWORK_ID, HttpStatus.SC_INTERNAL_SERVER_ERROR); - - // mockOpenStackGetStackCreated_200("OpenstackResponse_Stack_Created.json", NETWORK_ID); - - String uri = "/services/NetworkAdapter"; - headers.set("X-ECOMP-RequestID", "123456789456127"); - ResponseEntity<String> response = - sendXMLRequest(inputStream("/DeleteNetwork.xml").replace("CONTRAIL30_BASIC", "CONTRAIL31_GNDIRECT"), - uri, HttpMethod.POST); - assertEquals(Response.Status.INTERNAL_SERVER_ERROR.getStatusCode(), response.getStatusCode().value()); - } - - @Test - public void updateNetworkNeutronModeSuccess() throws IOException { - - mockOpenStackResponseAccess(wireMockServer, wireMockPort); - - mockOpenStackGetNeutronNetwork(wireMockServer, "GetNeutronNetwork.json", NETWORK_ID, HttpStatus.SC_OK); - mockOpenStackPutNeutronNetwork_200(wireMockServer, "OpenstackCreateNeutronNetworkResponse.json", NETWORK_ID); - - String uri = "/services/NetworkAdapter"; - headers.set("X-ECOMP-RequestID", "123456789456127"); - ResponseEntity<String> response = - sendXMLRequest(inputStream("/UpdateNetwork.xml").replace("CONTRAIL30_BASIC", "CONTRAIL31_GNDIRECT"), - uri, HttpMethod.POST); - assertEquals(Response.Status.OK.getStatusCode(), response.getStatusCode().value()); - } - @Test public void updateNetworkNeutronUpdateException() throws IOException { @@ -487,21 +352,6 @@ public class MSONetworkAdapterImplTest extends BaseRestTestUtils { assertEquals(Response.Status.OK.getStatusCode(), response.getStatusCode().value()); } - @Test - public void queryNetworkNeutronModeException() throws IOException { - - mockOpenStackResponseAccess(wireMockServer, wireMockPort); - - mockOpenStackGetNeutronNetwork(wireMockServer, NETWORK_ID, HttpStatus.SC_INTERNAL_SERVER_ERROR); - - String uri = "/services/NetworkAdapter"; - headers.set("X-ECOMP-RequestID", "123456789456127"); - ResponseEntity<String> response = - sendXMLRequest(inputStream("/QueryNetwork.xml").replace("CONTRAIL30_BASIC", "CONTRAIL31_GNDIRECT"), uri, - HttpMethod.POST); - assertEquals(Response.Status.INTERNAL_SERVER_ERROR.getStatusCode(), response.getStatusCode().value()); - } - public ResponseEntity<String> sendXMLRequest(String requestJson, String uriPath, HttpMethod reqMethod) { headers.set("Accept", MediaType.APPLICATION_XML); headers.set("Content-Type", MediaType.APPLICATION_XML); diff --git a/docs/api/offered_consumed_apis.rst b/docs/api/offered_consumed_apis.rst index 1d0a8f005b..0b0ba81b4d 100644 --- a/docs/api/offered_consumed_apis.rst +++ b/docs/api/offered_consumed_apis.rst @@ -1,6 +1,7 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 .. Copyright 2018 Huawei Technologies Co., Ltd. +.. _offeredapis: SO Offered and Consumed APIs ============================ |