adapters/mso-adapter-utils/src/main/java/org/openecomp/mso/adapters/vdu/VduPlugin.java

   1 /*-\r
   2  * ============LICENSE_START=======================================================\r
   3  * ONAP - SO\r
   4  * ================================================================================\r
   5  * Copyright (C) 2018 AT&T Intellectual Property. All rights reserved.\r
   6  * ================================================================================\r
   7  * Licensed under the Apache License, Version 2.0 (the "License");\r
   8  * you may not use this file except in compliance with the License.\r
   9  * You may obtain a copy of the License at\r
  10  *\r
  11  *      http://www.apache.org/licenses/LICENSE-2.0\r
  12  *\r
  13  * Unless required by applicable law or agreed to in writing, software\r
  14  * distributed under the License is distributed on an "AS IS" BASIS,\r
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  16  * See the License for the specific language governing permissions and\r
  17  * limitations under the License.\r
  18  * ============LICENSE_END=========================================================\r
  19  */\r
  20 \r
  21 package org.openecomp.mso.adapters.vdu;\r
  22 \r
  23 /**\r
  24  * This interface defines a common API for template-based cloud deployments.\r
  25  * The methods here should be adaptable for Openstack (Heat), Cloudify (TOSCA),\r
  26  * Aria (TOSCA), Multi-VIM (TBD), and others (e.g. Azure Resource Manager).\r
  27  * \r
  28  * The deployed instances are referred to here as Virtual Deployment Units (VDUs).\r
  29  * The package of templates that define a give VDU is referred to as its blueprint.\r
  30  * \r
  31  * Template-based orchestrators all follow a similar template/blueprint model.\r
  32  * - One main template that is the top level definition\r
  33  * - Optional nested templates referenced/included by the main template\r
  34  * - Optional files attached to the template package, typically containing\r
  35  *   configuration files, install scripts, orchestration scripts, etc.\r
  36  *   \r
  37  * The main template also defines the required inputs for creating a new instance,\r
  38  * and output values exposed by successfully deployed instances.  Inputs and outputs\r
  39  * may include simple or complex (JSON) data types.\r
  40  *   \r
  41  * Each implementation of this interface is expected to understand the MSO CloudConfig\r
  42  * to obtain the credentials for its sub-orchestrator and the targeted cloud.\r
  43  * The sub-orchestrator may have different credentials from the cloud (e.g. an Aria \r
  44  * instance in front of an Openstack cloud) or they may be the same (e.g. Heat)\r
  45  */\r
  46 import java.util.Map;\r
  47 \r
  48 public interface VduPlugin {\r
  49 \r
  50     /**\r
  51      * The instantiateVdu interface deploys a new VDU instance from a vdu model package.\r
  52      * \r
  53      * For some VIMs, this may be a single command (e.g. Heat -> create stack) or may\r
  54      * require a series of API calls (e.g. Cloudify -> upload blueprint, create deployment,\r
  55      * execute install workflow).  These details are hidden within the plug-in implementation.\r
  56      * The instantiation should be fully completed before returning.  On failures, this\r
  57      * method is expected to back out the attempt, leaving the cloud in its previous state.\r
  58      * \r
  59      * It is expected that parameters have been validated and contain at minimum the\r
  60      * required parameters for the given template with no extra parameters.\r
  61      *\r
  62      * The VDU name supplied by the caller will be globally unique, and identify the artifact\r
  63      * in A&AI.  Inventory is managed by the higher levels invoking this function.\r
  64      *\r
  65      * @param cloudInfo The target cloud + tenant identifiers for the VDU.\r
  66      * @param instanceName A unique name for the VDU instance to update.\r
  67      * @param inputs A map of key/value inputs.  Values may be strings, numbers, or JSON objects.\r
  68      *          Will completely replace any inputs provided on the original instantiation.\r
  69      * @param vduModel Object containing the collection of templates and files that comprise\r
  70      *          the blueprint for this VDU.\r
  71      * @param rollbackOnFailure Flag to preserve or roll back the update on Failure.  Should normally\r
  72      *          be True except in troubleshooting/debug cases.  Might not be supported in all plug-ins.\r
  73      * \r
  74      * @return A VduInstance object\r
  75      * @throws VduException Thrown if the sub-orchestrator API calls fail or if a timeout occurs.\r
  76      * Various subclasses of VduException may be thrown.\r
  77      */\r
  78     public VduInstance instantiateVdu (\r
  79                                 CloudInfo cloudInfo,\r
  80                                 String instanceName,\r
  81                                 Map<String,Object> inputs,\r
  82                                 VduModelInfo vduModel,\r
  83                                 boolean rollbackOnFailure)\r
  84                         throws VduException;\r
  85     \r
  86     /**\r
  87      * Query a deployed VDU instance.  This call will return a VduInstance object, or null\r
  88      * if the deployment does not exist.\r
  89      * \r
  90      * Some VIM orchestrators identify deployment instances by string UUIDs, and others \r
  91      * by integers.  In the latter case, the ID will be passed in as a numeric string.\r
  92      *\r
  93      * The returned VduInstance object contains the input and output parameter maps,\r
  94      * as well as other properties of the deployment (name, status, last action, etc.).\r
  95      * \r
  96      * @param cloudInfo The target cloud + tenant identifiers for the VDU.\r
  97      * @param vduInstanceId The ID of the deployment to query\r
  98      * \r
  99      * @return A VduInstance object\r
 100      * @throws VduException Thrown if the sub-orchestrator API calls fail or if a timeout occurs.\r
 101      * Various subclasses of VduException may be thrown.\r
 102      */\r
 103     public VduInstance queryVdu (\r
 104                                 CloudInfo cloudInfo,\r
 105                                 String vduInstanceId)\r
 106                         throws VduException;\r
 107 \r
 108     \r
 109     /**\r
 110      * Delete a VDU instance by ID.  If the VIM sub-orchestrator supports pre-installation\r
 111      * of blueprints/models, the blueprint itself may remain installed.  This is recommended,\r
 112      * since other VDU instances may be using it.\r
 113      * \r
 114      * Some VIM orchestrators identify deployment instances by string UUIDs, and others \r
 115      * by integers.  In the latter case, the ID will be passed in as a numeric string.\r
 116      * \r
 117      * For some VIMs, deletion may be a single command (e.g. Heat -> delete stack) or a\r
 118      * series of API calls (e.g. Cloudify -> execute uninstall workflow, delete deployment).\r
 119      * These details are hidden within the plug-in implementation.  The deletion should be\r
 120      * fully completed before returning.    \r
 121      *  \r
 122      * The successful return is a VduInstance object which contains the state of the VDU\r
 123      * just prior to deletion, with a status of DELETED.  If the deployment was not found,\r
 124      * the VduInstance object should be empty (with a status of NOTFOUND).\r
 125      * There is no rollback from a successful deletion.\r
 126      * \r
 127      * A deletion failure will result in an undefined deployment state - the components may\r
 128      * or may not have been all or partially uninstalled, so the resulting deployment must\r
 129      * be considered invalid.\r
 130      *\r
 131      * @param cloudInfo The target cloud + tenant identifiers for the VDU.\r
 132      * @param instanceId The unique id of the deployment to delete.\r
 133      * @param timeoutMinutes Timeout after which the delete action will be cancelled.\r
 134      *          Consider sending the entire model here, if it may be of use to the plug-in?\r
 135      * \r
 136      * @return A VduInstance object, representing its state just prior to deletion.\r
 137      * \r
 138      * @throws VduException Thrown if the API calls fail or if a timeout occurs.\r
 139      * Various subclasses of VduException may be thrown.\r
 140      */\r
 141     public VduInstance deleteVdu (\r
 142                                 CloudInfo cloudInfo,\r
 143                                 String instanceId,\r
 144                                 int timeoutMinutes)\r
 145                         throws VduException;\r
 146 \r
 147     \r
 148     /**\r
 149      * The updateVdu interface attempts to update a VDU in-place, using either new inputs or\r
 150      * a new model definition (i.e. updated templates/blueprints).  This depends on the\r
 151      * capabilities of the targeted sub-orchestrator, as not all implementations are expected\r
 152      * to support this ability.  It is primary included initially only for Heat.\r
 153          *\r
 154      * It is expected that parameters have been validated and contain at minimum the required\r
 155      * parameters for the given template with no extra parameters.  The VDU instance name cannot\r
 156      * be updated. \r
 157      * \r
 158          * The update should be fully completed before returning. The successful return is a\r
 159          * VduInstance object containing the updated VDU state.\r
 160      * \r
 161      * An update failure will result in an undefined deployment state - the components may\r
 162      * or may not have been all or partially modified, deleted, recreated, etc.  So the resulting\r
 163      * VDU must be considered invalid.\r
 164      * \r
 165      * @param cloudInfo The target cloud + tenant identifiers for the VDU.\r
 166      * @param instanceId The unique ID for the VDU instance to update.\r
 167      * @param inputs A map of key/value inputs.  Values may be strings, numbers, or JSON objects.\r
 168      *          Will completely replace any inputs provided on the original instantiation.\r
 169      * @param vduModel Object containing the collection of templates and files that comprise\r
 170      *          the blueprint for this VDU.\r
 171      * @param rollbackOnFailure Flag to preserve or roll back the update on Failure.  Should normally\r
 172      *          be True except in troubleshooting/debug cases.  Might not be supported in all plug-ins.\r
 173      * \r
 174      * @return A VduInfo object\r
 175      * @throws VduException Thrown if the sub-orchestrator API calls fail or if a timeout occurs.\r
 176      * Various subclasses of VduException may be thrown.\r
 177      */\r
 178     public VduInstance updateVdu (\r
 179                         CloudInfo cloudInfo,\r
 180                         String instanceId,\r
 181                         Map<String,Object> inputs,\r
 182                         VduModelInfo vduModel,\r
 183                         boolean rollbackOnFailure)\r
 184                                         throws VduException;\r
 185 \r
 186 }