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