2 * ============LICENSE_START=======================================================
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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=========================================================
20 package org.onap.so.vdu.utils;
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).
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.
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.
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.
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)
47 import org.onap.so.openstack.exceptions.MsoException;
49 public interface VduPlugin {
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.
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.
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.
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.
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
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.
86 public VduInfo instantiateVdu (
89 String vduInstanceName,
90 VduBlueprint vduBlueprint,
91 Map <String, ?> inputs,
92 String environmentFile,
94 boolean suppressBackout)
99 * Query a deployed VDU instance. This call will return a VduInfo object, or null
100 * if the deployment does not exist.
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.
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.).
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
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.
116 public VduInfo queryVdu (
119 String vduInstanceId)
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.
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.
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.
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.
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.
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
150 * @return A VduInfo object, representing the state of the instance just prior to deletion.
152 * @throws MsoException Thrown if the API calls fail or if a timeout occurs.
153 * Various subclasses of MsoException may be thrown.
155 public VduInfo deleteVdu (
158 String vduInstanceId,
160 boolean keepBlueprintLoaded)
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.
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
174 * The update should be fully completed before returning. The successful return is a
175 * VduInfo object containing the updated VDU state.
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.
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
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.
196 public VduInfo updateVdu (
199 String vduInstanceId,
200 VduBlueprint vduBlueprint,
201 Map <String, ?> inputs,
202 String environmentFile,
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.
212 * @param cloudSiteId The cloud site where the blueprint is needed
213 * @param vduModelId Unique ID of the VDU model to query
215 * @throws MsoException Thrown if the API call fails.
217 public boolean isBlueprintLoaded (String cloudSiteId, String vduModelId)
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.
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
233 * @throws MsoException Thrown if the API call fails.
235 public void uploadBlueprint (String cloudSiteId,
236 VduBlueprint vduBlueprint,
237 boolean failIfExists)
241 * Indicator that this VIM sub-orchestrator implementation supports independent upload
242 * of blueprint packages. Each implementation should return a constant value.
244 * @returns True if the sub-orchestrator supports blueprint pre-installation (upload).
246 public boolean blueprintUploadSupported ();