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

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