Upgrading an assembly instance

Once an assembly has been created it can be upgraded. An assembly instance can be upgraded to a new type, or have changed property values, or both new type and property values. This topic describes how to upgrade an assembly instance, with examples of how to change types and add a component.

Before you begin

The assembly to be upgraded should be instantiated in the orchestration topology and must be in the active state.

For the following example, you must have created the example assembly instance called test_1, as described in Creating an assembly instance.

About this task

You upgrade assembly instances by using the Intents API. For more information about this API, see Intents API.

This task upgrades a property of the test_1 assembly instance of the type t_single::1.0 to the type t_single::1.1, which also has an additional component named B.

Supported assembly upgrade scenarios

Definition of an assembly upgrade: Change an active assembly instance from its current type and set of properties to a new type and/or new property values.; The type of a component instance is determined by [assembly|resource]::<type name>::<version>; If the name of a property in the original and new type are the same, then they are assumed to be the same and can be mapped from the original to new properties.; If a property value is changed in a component, then the component will be re-installed with the new value.; If there is a new relationship between components of the new assembly type, the relationship is created. This may mean that a component must be transitioned to the correct states to create the new relationship.; If a relationship between components is removed from the upgraded assembly, the relationship is deleted.; If a property value of a relationship changes, then the relationship is deleted and re-created. This may mean that a component must be transitioned to the correct states to create the new relationship.; If a component, identified by name and type is not in the new assembly it is uninstalled.; If a component, identified by name and type is not in the original assembly it is created and transitioned to the active state.; If an assembly’s properties are changed, only the resources impacted are changed, resources that are not impacted and are unchanged. That is, if after an upgrade, a resource has the same name, type and property values, then it will not be transitioned during the upgrade; it will remain in the active state, unless a transition was triggered by a relationship change.; If a component's descriptor changes in any way, it is expected that the type will have changed (that is, there is a new type name and or version) and the component will be re-installed.; If a reference to an external component is removed from the assembly then any relationships referring to it will be deleted.; If a reference to an external component is added to the assembly then any relationships referring to it will be created.; The size of a cluster before an upgrade is maintained after the upgrade.; Restriction: Changing cluster property values to initial-quantity, minimum-nodes, maximum-nodes, or scaling-increment is not currently supported by the Assembly Upgrade pattern.

Procedure

Obtain a copy of t_simple::1.0 by browsing the catalog. Run the following query on the Descriptors API to find it:
```
GET /api/v1/catalog/descriptors
```
Change the version to t_simple::1.1

Add a new resource B to the composition table by copying resource A and changing it as depicted in the following example:

B:
    type: resource::t_simple::1.1
    quantity: '1'
    properties:
      referenced-internal-network:
        value: ${internal-network.id}
      reference-public-network:
        value: ${public-network.id}
      image:
        value: ${xenial-image.id}
      key_name:
        value: "ACCANTO_TEST_KEY"
      data:
        value: ${data}
      output:
        value: "B_output"  
      deploymentLocation:
        value: ${deploymentLocation}
      resourceManager:
        value: ${resourceManager}

Create a new assembly descriptor in the orchestration catalog called assembly::t_single::1.1 by running the following request on the Descriptors API.
```
POST /api/v1/catalog/descriptors/assembly::t_single::1.1
```
Query the assembly topology for the assembly instance test_1 by using the following Assemblies API request.
```
GET /api/v1/topology/assemblies?name=test_1
```
The assembly type for test_1 will be assembly::t_single::1.0, and there will not be a component of type B.

Upgrade of assembly instance.

POST /api/v1/intent/upgradeAssembly
{
  "assemblyName": "test_1",
  "descriptorName": "assembly::t_single::1.1"
}

Verify the updated assembly instance test_1 by using the following Assemblies API request.
```
GET /api/v1/topology/assemblies?name=test_1
```
The assembly type for test_1 will be assembly::t_single::1.1, and there will be a new component of type B.