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

@startuml
Title Migration Sequence
participant UserRest
participant ACM
participant ParticipantsDB
participant DBParticipants

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 : Comp Def IDs change for instance and AC Element instance and AC Element will be set\nin a transitional state (MIGRATING),\n new instance properties will be saved
  ACM -> Participants : Migration Movemessage from source to target compostioncomposition
  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.

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 endpoint:
PUT /onap/policy/clamp/acm/v2/compositions/{{source_composition_id}}/instances/{{instance_id}}

{
    deployOrder = "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.

Retry and TimeOut are supported.

Rollback:
PUT /onap/policy/clamp/acm/v2/compositions/{{source_composition_id}}/instances/{{instance_id}}

{
    deployOrder = "MIGRATION_ROLLBACK",
    compositionTarget = "{{target_composition_id}}"
}

Solution 3

Migrate using update endpoint:
POST /onap/policy/clamp/acm/v2/compositions/{{source_composition_id}}/instances/{{instance_id}}

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 id inverted.

If migration fail, the instance is still based to {{source_composition_id}} with deployState "MIGRATING" and stateChangeResult "FAILED". In this scenario, is it possible to retry or rollback the migration.

Retry and TimeOut are supported.

Rollback:
POST /onap/policy/clamp/acm/v2/compositions/{{source_composition_id}}/instances/{{instance_id}}

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.
  

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 /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}}

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
    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}}
  

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.