...

Note: KeyValuePairs data type is typically realized as Hashmap or Hashtable

CreateAsRequest

Note: 

1. The additional parameters can be passed to define custom values. All keys that are separated by dots are handled as separate values. Passing a value file content is under consideration. Special characters are allowed to represent \n, \., etc.
2. The target cluster name could be passed thru additionalParams if the client wants to select the target cluster.

...

• POST .../as_instances/{asInstanceId}/instantiate (InstantiateAsRequest)
• 202 Accepted ()
• Send asLcmOperationOccurrenceNotification (STARTING/PROCESSING/COMPLETED)
• 200 OK (AsLcmOpOcc:operationState=COMPLETED)

InstantiateAsRequest

Note: 

1. The additional parameters can be passed to define custom values. All keys that are separated by dots are handled as separate values. Passing a value file content is under consideration. Special characters are allowed to represent \n, \., etc.
2. The target cluster name could be passed thru additionalParams if the client wants to select the target cluster.

ExtCpdParams

DeploymentItems

Note: 

1. provides instance-level key-value sets for the Helm Charts values file(s).

...

• POST .../as_instances/{asInstanceId}/terminate (TerminateAsRequest)
• 202 Accepted ()
• Send asLcmOperationOccurrenceNotification (STARTING/PROCESSING/COMPLETED)
• 200 OK (AsLcmOpOcc:operationState=COMPLETED)

TerminateAsRequest

Delete AS Instance Resource

...

AsInstance for Create and Query

datatype.instantiationAsInfo

datatype._links

Register K8S Clusters

To instantiate an AS on an non-ONAP K8S cluster, a cluster configuration file that is specific to the cluster must be uploaded.

...

The following is ASD LCM Restful API Swagger file (work in progress)

• View filenameASLifecycleManagement-API-v10.yamlheight250

Kubernetes Resource Query

...

GET /api/v1/nodes

with parameters

...

Based on the node label (which is not unique), get a node list. To narrow it further, use the additional findSelector parameter. 

...

Query Cluster POD by name

...

• kubectl get ns -A
• kubectl get pods - n <namespace>
• kubectl get pod -o=custom-columns=NAME:.metadata.name,NODE:.spec.nodeName
• kubectl get pod -o=custom-columns=NAME:.metadata.name,NODE:.spec.nodeName | awk '{print $2}'.                                         // get the node name
• kubectl get pod -o=custom-columns=NAME:.metadata.name,NODE:.spec.nodeName | grep <release name>.                               // get the pod and node names for release name
• kubectl get pod -o=custom-columns=NAME:.metadata.name,NODE:.spec.nodeName | grep <release name> | awk '{print $2}'.  // get the node name for release name
• kubectl describe pods <pod name>       // get a pod description
• kubectl describe pods <pod name> | grep 'Container ID'.    // get container id(s) from a pod
• kubectl get pod <pod name>  -o="custom-columns=NAME:.metadata.name,INIT-CONTAINERS:.spec.initContainers[*].name,CONTAINERS:.spec.containers[*].name".   // get pod, init-container and containers
• kubectl get pods <pod name>  -o jsonpath='{range .spec.containers[*]}{.name}{"\n"}{end}'.   // get container name(s) from the pod name
• kubectl exec -it <pod name> -c <container name> bash.  // access pod

API Use in ONAP SO

Create and Instantiate AS

• <Preconditions>:
  • Registar K8S Cluster(s) to ONAP
  • During the registration, SO CNFM creates .kube/{target K8S cluster name}.config file(s)

• <SO BPMN Infra>
  • BPMN Infra workflow gets VF Resource TOSCA.meta. 
  • In there, the entity_defintion_type is found and it is set to "asd", BPMN infra launches the AS LCM Workflow as the above.
  • The workflows sends a request for Create AS Identifier to SO CNFM

• <Create an AS Identifier>
  • SO CNFM receives the create request (CreateAsRequest) and processes the request and return a response with AsInstance

    • CreateAsRequest:

      asdId	Identifier (UUID)	1	Identifier that identifies the ASD which defines the AS instance to be created.
      asInstanceDescription	String	0..1	Human-readable description of the AS instance to be created.
      asInstanceName	String	0..1	Human-readable name of the AS instance to be created.

      
      

    • The client passes "asdId" to SO CNFM, so CNFM can query an ASD with the asdId from the ASD Repository

    • SO CNFM copies the incoming CreateAsRequest attributes into an AsInstance structure, and persists the AsInstance, which has a connection between the asInstanceId and asdId
    • note: SO CNFM will uses the asdId when it queries an ASD from the ASD Repository during the instantiation operation

      
      

  • When the Create AS instance is successful, SO CNFM returns 200 OK with the AsInstance
    • The returned AsInstance contains the asInstanceId
    • Subsequent operations uses the asInstanceId; i.e., the Client use the asIstanceId in the REST Api path

• <Instantiate an AS>
  • BPMN Infra sends an AS instantiate request to SO CNFM with the asInstanceId as follows:
    • POST .../as_instances/{asInstanceId}/instantiate (InstantiateAsRequest)
    • InstantiateAsRequest

      
      

      Attribute Name	Data Type	Cardinality	Description
      asdExtCpdInputParams	ExtCpdParams	0..N	contains ext cpd parameter instance-level value
      deploymentItems	DeploymentItems	1..N	contains lifecycle parameters for deploymentItems
      additionalParams	KeyValuesPairs	0..1	Additional input parameters for the instantiation process (this is a pace holder to hold any additional parameters which are needed by SO CNFM)

      
      

  • SO CNFM retrieves the corresponding AsInstance from its DB; it is retrieve the "asdId" for the ASD query
  • SO CNFM queries an ASD with the asdId from the ASD Repository; caches the retrieved ASD in the memory during the Instantiate operations
  • SO CNFM reads thru the ASD DeploymentItems, and per deploymentItems, SO CNFM queries for the associated Helm Chart (1:1) from the Helm Chart Repository
    • caches the retrieved Helm Charts in the memory during the Instantiate operations
  • SO CNFM reads the deploymentItems.deploymentOrder. Based on the order sequence, SO CNFM processes the deploymentItems one by one
  • For each, deployment item,
    • SO CNFm creates vf-modules in AAI
    • SO CNFM assignes vf-modules in SDNC
    • From the InstantiateAsRequest, SO CNFM retrieves the deploymentItems

      • DeploymentItems

        deploymentItemId	Identifier	1	Identifies which deploymentItem
        lifecycleParameterKeyValues	KeyValuesPairs	0..N	provides lifecycle parameter keys and values

        
        

      • The lifecycleParameterKeyValues contains a list of customizable attributes (key) in the values.yaml with instance-level values
    • From the associated Helm Chart, SO CNFM gets the values.yaml
    • SO CNFM creates a new values.yaml, based on the retrieved values.yaml + lifecycleParameterKeyValues
    • ==== SO CNFM processes the asdExtCpdInputParam ==== TBD
    • SO CNFM performs "helm template " to render K8S resource template(s)
    • With the rendered k8S resource template(s), SO CNFM gets a placement decision from the Placement component (e.g., OOF)
      • Currently, use of OOF is out of the scope from the initial PoC
      • In the initial PoC, a simplified placement function will be used
    • Based on the placement decision, SO CNFM determines the target K8S cluster
    • Set the Helm command environment to connect to the target K8S cluster
      • set .kube/{target K8S cluster name}.config
    • SO CNFM invokes "helm install" command with the corresponding Helm Chart and a new values.yaml
      • SO CNFM will have a few South-Bound plugin (helm client, CNF Adapter, others)
      • in the initial PoC, the helm client will be used
      • SO CNFM Helm Client will select a target Kubernetes cluster
        • e.g., helm install <release> <chart> --kubeconfig ~/.kubeconfigs/<cluster_name>.kubeconfig
        • in the initial PoC, the target cluster is selected by the user and its name will be passed thru the user params (in SO) and additionalParams (in SO-CNFM)
    • If successful, SO CNFM update the corresponding vf-module in the AAI

• <Postconditions>:
  • each POD is a Ready status. This ensures that each POD can serve requests.
  • Some of the PODs will not reach the Ready status until a day 1 configuration is applied
  • The PODs still need verification of containers with a specific ContainerState

@startuml
participant SO_Client
participant SO
participant SO_BPMN
participant CNFM
participant AAI
participant SDNC
participant OOF
participant ASD_Catalog_Mgr
participant Helm_Repository
participant K8S_Cluster

autonumber 

group ASD-Based CNF Instantiation
    SO_Client -> SO : Create Service
    SO -> SO_BPMN : Process and Decompose Service
    SO_BPMN -> AAI : Create Service Instance
opt Service-Level Homing
    SO_BPMN -> OOF : Homing Information (optional for PoC)
    OOF -> SO_BPMN : Receive Homing Information (optional for PoC)
end
    SO_BPMN --> SO_BPMN : Process Model Info & Decide flows      
    SO_BPMN -> CNFM : Delegate Resource Orchestration,\npass input parameters
    CNFM -> ASD_Catalog_Mgr : Get ASD
    CNFM -> Helm_Repository : Get associated Helm Charts
    CNFM --> CNFM : Process and decompose ASD and DeploymentItems\n(VF & Vf-Modules)
    CNFM --> CNFM : get DeploymentItem order and create a sequence list
    CNFM --> CNFM : execute each deployment item by following the sequence order
loop
    CNFM -> AAI : Create vf-module
    CNFM -> SDNC : Assign vf-module
    CNFM --> CNFM : Get AsInstance LifecycleParameterMetadata from the request
    CNFM --> CNFM : Get the corresponding Helm Chart
    CNFM --> CNFM : Create a new values file by replacing the values file from the Helm Chart with LifecycleParameterMetadata
    CNFM --> CNFM : generate K8S resource (e.g., helm template) based on the Helm Chart plus a new custom values file
    CNFM -> OOF : get a placement decision (for PoC, returns a predefined K8S cluster name)
	CNFM --> CNFM: set kube config environment for the target K8S Cluster
    CNFM --> K8S_Cluster : invoke Helm Install with a custom values file
    CNFM -> AAI : Update vf-module

end
end  



@enduml

AS LCM APIs

Create an AS Identifier

In order for an application (CNF) to be eligible for instantiation, a CNF identifier must be created to identify the application service as a unique instance.

An AS instance supports multiple deployment items (helm charts). So, the AS instance id could be used for helm release names as the prefix.

Query AS Instance Identifiers

To list all AS instances, make a GET request to SO CNFM.

GET .../aslcm/v1/as_instances

Query an AS instance by Instance ID

To query a specific AS instance by its instance ID, make a GET request to SO CNFM.

GET .../aslcm/v1/as_instances/{asInstanceId}

Instantiate an AS

• To instantiate an AS, make a poST request to SO CNFM. The target cluster name is included in the requrest parameter.

POST .../as_instances/{asInstanceId}/instantiate

• if some of the parameters required for instantiation are complex and cannot fit into the additionalParams section of the JSON request body (TBD).

Upgrading an AS

This operation is referred to as the changing of an AS package.

POST .../as_instances/{asInstanceId}/change_aspkg

Terminate an AS Instance

This operation terminates an AS instance.

POST .../as_instances/{asInstnaceId}/terminate (TerminateAsRequest)

Note: for PoC, GRACEFUL termination type is not supported.

Delete an AS Identifier

This operation deletes an AS Identifier.

DELETE .../as_instances/{as_instanceId}

Note: optionally, Delete an AS Identifier could clean up resources of an AS Instance, e.g., Persistent Volumes (PVs)

The Delete operation may need to update AAI.