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

   1 /*-
   2  * ============LICENSE_START=======================================================
   3  * ONAP - SO
   4  * ================================================================================
   5  * Copyright (C) 2017 AT&T Intellectual Property. All rights reserved.
   6  * ================================================================================
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  *      http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  * ============LICENSE_END=========================================================
  19  */
  20 package org.openecomp.mso.vdu.utils;
  21
  22 /**
  23  * This interface defines a common API for template-based cloud deployments.
  24  * The methods here should be adaptable for Openstack (Heat), Cloudify (TOSCA),
  25  * Aria (TOSCA), Multi-VIM (TBD), and others (e.g. Azure Resource Manager).
  26  *
  27  * The deployed instances are referred to here as Virtual Deployment Units (VDUs).
  28  * The package of templates that define a give VDU is referred to as its blueprint.
  29  *
  30  * Template-based orchestrators all follow a similar template/blueprint model.
  31  * - One main template that is the top level definition
  32  * - Optional nested templates referenced/included by the main template
  33  * - Optional files attached to the template package, typically containing
  34  *   configuration files, install scripts, orchestration scripts, etc.
  35  *
  36  * The main template also defines the required inputs for creating a new instance,
  37  * and output values exposed by successfully deployed instances.  Inputs and outputs
  38  * may include simple or complex (JSON) data types.
  39  *
  40  * Each implementation of this interface is expected to understand the MSO CloudConfig
  41  * to obtain the credentials for its sub-orchestrator and the targeted cloud.
  42  * The sub-orchestrator may have different credentials from the cloud (e.g. an Aria
  43  * instance in front of an Openstack cloud) or they may be the same (e.g. Heat)
  44  */
  45 import java.util.Map;
  46
  47 import org.openecomp.mso.openstack.exceptions.MsoException;
  48
  49 public interface VduPlugin {
  50
  51     /**
  52      * The instantiateVdu interface deploys a new VDU instance from a blueprint package.
  53      * The templates and files in the blueprint may be pre-installed where supported
  54      * (e.g. in Cloudify or Aria), or may be passed in directly (e.g. for Heat).  These
  55      * files are expressed as byte arrays, though only text files are expected from ASDC.
  56      *
  57      * For some VIMs, this may be a single command (e.g. Heat -> create stack) or may
  58      * require a series of API calls (e.g. Cloudify -> upload blueprint, create deployment,
  59      * execute install workflow).  These details are hidden within the implementation.
  60      * The instantiation should be fully completed before returning.  On failures, this
  61      * method is expected to back out the attempt, leaving the cloud in its previous state.
  62      *
  63      * It is expected that parameters have been validated and contain at minimum the
  64      * required parameters for the given template with no extra parameters.
  65      *
  66      * The VDU name supplied by the caller will be globally unique, and identify the artifact
  67      * in A&AI.  Inventory is managed by the higher levels invoking this function.
  68      *
  69      * @param cloudSiteId The target cloud for the VDU.  Maps to a CloudConfig entry.
  70      * @param tenantId The cloud tenant in which to deploy the VDU.  The meaning may differ by
  71      *          cloud provider, but every cloud supports some sort of tenant partitioning.
  72      * @param vduInstanceName A unique name for the VDU instance to create
  73      * @param vduBlueprint Object containing the collection of templates and files that comprise
  74      *          the blueprint for this VDU.
  75      * @param inputs A map of key/value inputs.  Values may be strings, numbers, or JSON objects.
  76      * @param environmentFile A file containing default parameter name/value pairs.  This is
  77      *          primarily for Heat, though ASDC may create a similar file for other orchestrators.
  78      * @param timeoutMinutes Timeout after which the instantiation attempt will be cancelled
  79      * @param suppressBackout Flag to preserve the deployment on install Failure.  Should normally
  80      *          be False except in troubleshooting/debug cases
  81      *
  82      * @return A VduInfo object
  83      * @throws MsoException Thrown if the sub-orchestrator API calls fail or if a timeout occurs.
  84      * Various subclasses of MsoException may be thrown.
  85      */
  86     public VduInfo instantiateVdu (
  87                                 String cloudSiteId,
  88                                 String tenantId,
  89                                 String vduInstanceName,
  90                                 VduBlueprint vduBlueprint,
  91                                 Map <String, ?> inputs,
  92                                 String environmentFile,
  93                                 int timeoutMinutes,
  94                                 boolean suppressBackout)
  95                         throws MsoException;
  96
  97
  98     /**
  99      * Query a deployed VDU instance.  This call will return a VduInfo object, or null
 100      * if the deployment does not exist.
 101      *
 102      * Some VIM orchestrators identify deployment instances by string UUIDs, and others
 103      * by integers.  In the latter case, the ID will be passed in as a numeric string.
 104      *
 105      * The returned VduInfo object contains the input and output parameter maps,
 106      * as well as other properties of the deployment (name, status, last action, etc.).
 107      *
 108      * @param cloudSiteId The target cloud to query for the VDU.
 109      * @param tenantId The cloud tenant in which to query
 110      * @param vduInstanceId The ID of the deployment to query
 111      *
 112      * @return A VduInfo object
 113      * @throws MsoException Thrown if the VIM/sub-orchestrator API calls fail.
 114      * Various subclasses of MsoException may be thrown.
 115      */
 116     public VduInfo queryVdu (
 117                                 String cloudSiteId,
 118                                 String tenantId,
 119                                 String vduInstanceId)
 120                         throws MsoException;
 121
 122
 123     /**
 124      * Delete a VDU instance by ID.  If the VIM sub-orchestrator supports pre-installation
 125      * of blueprints, the blueprint itself may remain installed.  This is recommended, since
 126      * other VDU instances may be using it.
 127      *
 128      * Some VIM orchestrators identify deployment instances by string UUIDs, and others
 129      * by integers.  In the latter case, the ID will be passed in as a numeric string.
 130      *
 131      * For some VIMs, deletion may be a single command (e.g. Heat -> delete stack) or a
 132      * series of API calls (e.g. Cloudify -> execute uninstall workflow, delete deployment).
 133      * These details are hidden within the implementation.  The deletion should be fully
 134      * completed before returning.
 135      *
 136      * The successful return is a VduInfo object which contains the state of the object just prior
 137      * to deletion, with a status of DELETED.  If the deployment was not found, the VduInfo object
 138      * should be empty (with a status of NOTFOUND).  There is no rollback from a successful deletion.
 139      *
 140      * A deletion failure will result in an undefined deployment state - the components may
 141      * or may not have been all or partially uninstalled, so the resulting deployment must
 142      * be considered invalid.
 143      *
 144      * @param cloudSiteId The target cloud from which to delete the VDU.
 145      * @param tenantId The cloud tenant in which to delete the VDU.
 146      * @param vduInstanceId The unique id of the deployment to delete.
 147      * @param timeoutMinutes Timeout after which the delete action will be cancelled
 148      * @param keepBlueprintLoaded Flag to also delete the blueprint
 149      *
 150      * @return A VduInfo object, representing the state of the instance just prior to deletion.
 151      *
 152      * @throws MsoException Thrown if the API calls fail or if a timeout occurs.
 153      * Various subclasses of MsoException may be thrown.
 154      */
 155     public VduInfo deleteVdu (
 156                                 String cloudSiteId,
 157                                 String tenantId,
 158                                 String vduInstanceId,
 159                                 int timeoutMinutes,
 160                                 boolean keepBlueprintLoaded)
 161                         throws MsoException;
 162
 163
 164     /**
 165      * The updateVdu interface attempts to update a VDU in-place, using either new inputs or
 166      * a new model definition (i.e. updated templates/blueprints).  This depends on the
 167      * capabilities of the targeted sub-orchestrator, as not all implementations are expected
 168      * to support this ability.  It is primary included initially only for Heat.
 169          *
 170      * It is expected that parameters have been validated and contain at minimum the required
 171      * parameters for the given template with no extra parameters.  The VDU instance name cannot
 172      * be updated.
 173      *
 174          * The update should be fully completed before returning. The successful return is a
 175          * VduInfo object containing the updated VDU state.
 176      *
 177      * An update failure will result in an undefined deployment state - the components may
 178      * or may not have been all or partially modified, deleted, recreated, etc.  So the resulting
 179      * VDU must be considered invalid.
 180      *
 181      * @param cloudSiteId The target cloud for the VDU.  Maps to a CloudConfig entry.
 182      * @param tenantId The cloud tenant in which to deploy the VDU.  The meaning may differ by
 183      *          cloud provider, but every cloud supports some sort of tenant partitioning.
 184      * @param vduInstanceId The unique ID for the VDU instance to update.
 185      * @param vduBlueprint Object containing the collection of templates and files that comprise
 186      *          the blueprint for this VDU.
 187      * @param inputs A map of key/value inputs.  Values may be strings, numbers, or JSON objects.
 188      * @param environmentFile A file containing default parameter name/value pairs.  This is
 189      *          primarily for Heat, though ASDC may create a similar file for other orchestrators.
 190      * @param timeoutMinutes Timeout after which the instantiation attempt will be cancelled
 191      *
 192      * @return A VduInfo object
 193      * @throws MsoException Thrown if the sub-orchestrator API calls fail or if a timeout occurs.
 194      * Various subclasses of MsoException may be thrown.
 195      */
 196     public VduInfo updateVdu (
 197                                 String cloudSiteId,
 198                                 String tenantId,
 199                                 String vduInstanceId,
 200                                 VduBlueprint vduBlueprint,
 201                                 Map <String, ?> inputs,
 202                                 String environmentFile,
 203                                 int timeoutMinutes)
 204                         throws MsoException;
 205
 206
 207     /**
 208      * Check if a blueprint package has been installed in the sub-orchestrator and available
 209      * for use at a targeted cloud site.  If the specific sub-orchestrator does not support
 210      * pre-installation, then those implementations should always return False.
 211      *
 212      * @param cloudSiteId The cloud site where the blueprint is needed
 213      * @param vduModelId Unique ID of the VDU model to query
 214      *
 215      * @throws MsoException Thrown if the API call fails.
 216      */
 217     public boolean isBlueprintLoaded (String cloudSiteId, String vduModelId)
 218                         throws MsoException;
 219
 220
 221     /**
 222      * Install a blueprint package to the target sub-orchestrator for a cloud site.
 223      * The blueprints currently must be structured as a single directory with all of the
 224      * required files.  One of those files is designated the "main file" for the blueprint.
 225      * Files are provided as byte arrays, though expect only text files will be distributed
 226      * from ASDC and stored by MSO.
 227      *
 228      * @param cloudSiteId The cloud site where the blueprint is needed
 229      * @param vduBlueprint Object containing the collection of templates and files that comprise
 230      *          the blueprint for this VDU.
 231      * @param failIfExists Flag to return an error if blueprint already exists
 232      *
 233      * @throws MsoException Thrown if the API call fails.
 234      */
 235     public void uploadBlueprint (String cloudSiteId,
 236                                                         VduBlueprint vduBlueprint,
 237                                                         boolean failIfExists)
 238         throws MsoException;
 239
 240     /**
 241      * Indicator that this VIM sub-orchestrator implementation supports independent upload
 242      * of blueprint packages.  Each implementation should return a constant value.
 243      *
 244      * @returns True if the sub-orchestrator supports blueprint pre-installation (upload).
 245      */
 246     public boolean blueprintUploadSupported ();
 247
 248 }