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