This page contains details of planning and implementation of the migration functionality for instances in ACM-R. Rest interface users will be able to call a new endpoint in order to trigger the moving/migration of an instance from a source composition definition to a target composition definition. Calls to migrate the instance will take place on an instance-by-instance basis. The caller will have to supply the following parameters when making the call to migrate an instance.
- Source Composition Definition Id - The Id of the composition that the instance is currently based on.
- Target Composition Definition Id - The Id of the composition that the instance is to be migrated to.
- Instance Id - The Id of the instance that the caller wishes to migrate.
This operation will only be possible if:
- the source composition is primed
- the target composition is primed and contains the same element definitions present in the source composition
- the instance is deployed and based on the the source composition
Migration Sequence Diagram
Note: The functionality for the upload of a new composition definition already exists
| PlantUML Macro |
|---|
@startuml Title Migration Sequence participant UserRest participant ACM participant DB participant Participants group Create New Composition type for Migration UserRest -> ACM : Composition Definitions ACM -> DB : Saved Definition UserRest -> ACM : Prime Definition ACM -> Participants: Prime Definition end group group Migration per Instance /'Instance migration from source to target composition type. '/ UserRest -> ACM : Migrate Instance \n(InstanceId, sourceCompId, targetCompId, instance properties) note top Instance migration from source to target composition type. end note alt "instance Id and Composition Ids exist" ACM -> UserRest : 202 Async Operation ACM -> DB : Definition Validation (v1 no new elements/structure) ACM -> DB : instance and AC Element will be set\nin in a transitional state (MIGRADING)MIGRATING),\n new instance properties will be saved ACM -> Participants : Migration Movemessage from source to target composition Participants -> ACM : Move completed ACM -> DB : instance and AC Element will be set in a final state (DEPLOYED)\n and Comp Def IDs change for instance and AC Element else ACM -> UserRest : 400 Bad Reqest end end group @enduml |
End point, fail and rollback
Solution 1
Migrate using a new endpoint:
PUT /onap/policy/clamp/acm/v2/compositions/{{source_composition_id}}/instances/{{instance_id}}/migrate
{
compositionTarget = "{{target_composition_id}}"
}
After instance has been migrated successfully, it could be retrieved using:
GET /onap/policy/clamp/acm/v2/compositions/{{target_composition_id}}/instances/{{instance_id}}
In success scenario, is it possible to revert the migration, using the same endpoint with composition id inverted.
If migration fail, the instance is still based to {{source_composition_id}} with deployOrder "MIGRATING" and stateChangeResult "FAILED". In this scenario, is it possible to retry or rollback the migration, using the flag "rollback" set to true.
Retry and TimeOut are supported.
Rollback:
PUT /onap/policy/clamp/acm/v2/compositions/{{source_composition_id}}/instances/{{instance_id}}/migrate
{
rollback = "true",
compositionTarget = "{{target_composition_id}}"
}
Solution 2
Migrate using change state endpointRollback:
PUT /onap/policy/clamp/acm/v2/compositions/{{source_composition_id}}/instances/{{instance_id}}/migrate
{
rollback deployOrder = "trueMIGRATE",
compositionTarget = "{{target_composition_id}}"
}
Solution 2
After instance has been migrated successfully, it could be retrieved using:
GET /onap/policy/clamp/acm/v2/compositions/{{target_composition_id}}/instances/{{instance_id}}
In success scenario, is it possible to revert the migration, using the same endpoint with composition id inverted.
If migration fail, the instance is still based to {{source_composition_id}} with deployOrder "MIGRATING" and stateChangeResult "FAILED". In this scenario, is it possible to retry or rollback the migration.
Retry and TimeOut are supported.
RollbackMigrate:
PUT /onap/policy/clamp/acm/v2/compositions/{{source_composition_id}}/instances/{{instance_id}}
{
deployOrder = "MIGRATEMIGRATION_ROLLBACK",
compositionTarget = "{{target_composition_id}}"
}
Solution 3
Migrate using update endpoint:
POST /onap/policy/clamp/acm/v2/compositions/{{source_composition_id}}/instances/{{instance_id}}
| Code Block | ||||
|---|---|---|---|---|
| ||||
name: ExampleInstance0
version: 1.0.1
compositionId: {{compositionId}}
compositionTarget: {{target_composition_id}}
elements:
709c62b3-8918-41b9-a747-d21eb79c6c23:
id: 709c62b3-8918-41b9-a747-d21eb79c6c23
definition:
name: onap.policy.clamp.ac.element.ExampleAutomationCompositionElement
version: 1.2.3
properties:
propertyExample: new value |
After instance has been migrated successfully, it could be retrieved using:
GET /onap/policy/clamp/acm/v2/compositions/{{target_composition_id}}/instances/{{instance_id}}
In success scenario, is it possible to revert the migration, using the same endpoint with old properties values and composition ids id inverted.
If migration fail, the instance is still based to {{source_composition_id}} with deployOrder deployState "MIGRATING" and stateChangeResult "FAILED". In this scenario, is it possible to retry or rollback the migration, with the deployOrder set to "MIGRATION_ROLLBACK".
Retry and TimeOut are supported.
Rollback:
PUT POST /onap/policy/clamp/acm/v2/compositions/{{source_composition_id}}/instances/{{instance_id}}{
deployOrder = "MIGRATE",
compositionTarget = "
| Code Block | ||||
|---|---|---|---|---|
| ||||
name: ExampleInstance0
version: 1.0.1
compositionId: {{compositionId}}
compositionTarget: {{target_composition_id}}
rollback: true
elements:
709c62b3-8918-41b9-a747-d21eb79c6c23:
id: 709c62b3-8918-41b9-a747-d21eb79c6c23
definition:
name: onap.policy.clamp.ac.element.ExampleAutomationCompositionElement
version: 1.2.3
properties:
propertyExample: old value |
Final solution
- Migrate using update endpoint:
POST /onap/policy/clamp/acm/v2/compositions/{{source_composition_id}}/instances
"compositionTargetId" and new properties values will be saved in DB and available during migration operation.
| Code Block | ||||
|---|---|---|---|---|
| ||||
name: ExampleInstance0 version: 1.0.1 instanceId: {{instanceId}} compositionId: {{compositionId}} compositionTargetId: {{target_composition_id}} |
}
elements:
709c62b3-8918-41b9-a747-d21eb79c6c23:
id: 709c62b3-8918-41b9-a747-d21eb79c6c23
definition:
name: onap.policy.clamp.ac.element.ExampleAutomationCompositionElement
version: 1.2.3
properties:
propertyExample: new value |
- New MIGRATE message to be sent over Kafka to participant
- During migration operation, the instance will be available to retrieve by source and target composition:
GET /onap/policy/clamp/acm/v2/compositions/{{source_composition_id}}/instances
GET
Rollback:
PUT- /onap/policy/clamp/acm/v2/compositions/{{source_composition_id}}/instances/{{instance_id}}
GET /onap/policy/clamp/acm/v2/compositions/{{target_composition_id}}/instances/{{instance_id}}
| Code Block | ||||
|---|---|---|---|---|
| ||||
name: ExampleInstance0 version: 1.0.1 instanceId: {{instanceId}} compositionId: {{compositionId}} compositionTargetId: {{target_composition_id}} deployState: MIGRATING lockState: LOCKED elements: 709c62b3-8918-41b9-a747-d21eb79c6c23: id: 709c62b3-8918-41b9-a747-d21eb79c6c23 definition: name: onap.policy.clamp.ac.element.ExampleAutomationCompositionElement version: 1.2.3 deployState: MIGRATING lockState: LOCKED |
compositionTarget = "
properties:
propertyExample: new value |
Note: during migration the instance instance_id is not in target_composition_id yet, so that instance will be not available in "GET /onap/policy/clamp/acm/v2/compositions/{{target_composition_id}}/instances".
- After instance has been migrated successfully, it will be retrieved using:
GET /onap/policy/clamp/acm/v2/compositions/{{target_composition_id}}/instances
GET /onap/policy/clamp/acm/v2/compositions/{{target_composition_id}}/instances/{{instance_id}}
| Code Block | ||||
|---|---|---|---|---|
| ||||
name: ExampleInstance0
version: 1.0.1
instanceId: {{instanceId}}
compositionId: {{target_composition_id}}
deployState: DEPLOYED
lockState: LOCKED
stateChangeResult: NO_ERROR
elements:
709c62b3-8918-41b9-a747-d21eb79c6c23:
id: 709c62b3-8918-41b9-a747-d21eb79c6c23
definition:
name: onap.policy.clamp.ac.element.ExampleAutomationCompositionElement
version: 1.2.3
deployState: DEPLOYED
lockState: LOCKED
properties:
propertyExample: new value |
Note: The endpoint "GET /onap/policy/clamp/acm/v2/compositions/{{target_composition_id}}/instances/{{instance_id}}" is the suggested endpoint to use for checking the migration result.
- AutomationCompositionElementListener altered to allow participant to listen for migrate message:
- void migrate(UUID instanceId, AcElementDeploy element, UUID compositionTargetId, Map<String, Object> properties) throws PfModelException;
- If migration fail, the instance is still based to {{source_composition_id}} with deployState "MIGRATING" and stateChangeResult "FAILED". In this scenario the user will be allowed to undeploy and delete the instance.