Cisco Elastic Services Controller 4.2 User Guide

Bias-Free Language

The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.

Book Contents
Find Matches in This Book
Available Languages
Download Options

Book Title

Cisco Elastic Services Controller 4.2 User Guide

Chapter Title

Managing VNF Lifecycle Using ETSI API

Results

Updated:
August 13, 2018

Chapter: Managing VNF Lifecycle Using ETSI API

Managing VNF Lifecycle Using ETSI API

The NFVO communicates with ESC using the ETSI MANO API for lifecycle management of a VNF. A configuration template, the Virtual Network Function Descriptor (VNFD) file describes the deployment parameters and operational behaviors of a VNF type. The VNFD is used in the process of deploying a VNF and managing the lifecycle of a VNF instance.

The lifecycle operations of a VNF instance is as follows:

  1. Create a VNF Identifier—ESC generates a new VNF Instance Id (a universally unique identifier) that is subsequently used as a handle to reference the instance upon which to execute further operations.

  2. Instantiate / Deploy VNF—As part of VNF instantiation, ESC instantiates a new VNF instance in the VIM. ESC receives a request to instantiate a VNF instance from NFVO. The instantiate request contains resource requirements, networking and other service operational behaviors. All these requirements along with the VNFD and the grant information provides all the necessary information to instantiate the VNF.

  3. Operate VNF—ESC allows you to start and stop a VNF instance. The resources are not released or changed, but the VNF instance in the VIM is toggled between these two states.

  4. Query VNF—To query one or more VNF instances known to ESC. To query one or more VNF instances known to ESC. This is a specific REST end point that can be filtered to find specific instances. The instances can be filtered using the VNF Instance Id.

    Also, a separate REST end point allows the NFVO to query the status of one or more lifecycle operation occurrences associated with a VNF. The lifecycle operations can be filtered using a specific occurrence identifier.

  5. Modify VNF—ESC allows you to modify the properties of a single VNF instance. The instantiated VNF is updated, and the lifecycle management operation occurrence sends notification to the NFVO about the status of the VNF.

  6. Scale and Scale to Leve VNF—ESC allows you to scale VNFs in two ways. You can scale a VNF incrementally, or to a specific level.

  7. Heal VNF—ESC heals the VNF when there is a failure.

  8. Terminate / Undeploy VNF—To terminate the VNF instance in the VIM. The resources themselves remain reserved for the VNF instance, however the VNF itself is undeployed.

  9. Delete VNF Identifier—The resources are fully released in the VIM and in ESC and the associated VNF instance identifer is also released.

For VNF lifecycle operations using REST and NETCONF APIs, see Deploying and Configuring Virtual Network Functions.

VNF Lifecycle Operations Using ETSI API

Prerequisites

The following prerequisites must be met for VNF lifecycle operations:

  • The resource definitions must be created out of band and must be available before VNF instantiation.

  • The VIM connector specifies the VIM used. The VIM connector information must be available before instantiating the VNF. ESC must contain a valid, and authenticated default OpenStack VIM connector to deploy the VNFs.

  • The VNF to be instantiated has to be onboarded to the NFVO within an ETSI compliant VNF Package.

    • The NFVO must provide ETSI compliant VNF Packages to ESC.

    • The VNF package must contain a VNF Descriptor (VNFD) file.

    The ETSI MANO NFV specifications supports /vnf_packages API to allow access to the package artifacts.See chapter 10 in the ETSI GS NFV-SOL 003 V2.4.1 specification on the ETSI website.

    The properties file provides details about the NFVO to the ETSI VNFM service.

    The properties file, etsi-production.properties exists under: /opt/cisco/esc/esc_database/

    The single property nfvo.apiRoot allows specification of the NFVO host and port. For example, nfvo.apiRoot=localhost:8280.


Note

The initial implementation of the ETSI MANO API supports only a single VIM. The tenant/project is currently specified using the resourceGroupId.

For notes on ESC in HA mode, enabled with ETSI service, see the Cisco Elastic Services Controller Install and Upgrade Guide.

Creating the VNF Identifier

Creating the VNF Identifier is the first request for any VNF instance. This identifier is used for all further LCM operations executed by the ETSI API. Resources are neither created nor reserved at this stage.

ESC sends a POST request to create VNF instances:

Method Type: 
POST
VNFM Endpoint:
 /vnf_instances/
HTTP Request Headers: 
 Content-Type:application/json
Request Payload (ETSI data structure: CreateVnfRequest): 
{
    "vnfInstanceName": "Test-VNf-Instance",
    "vnfdId": "vnfd-88c6a03e-019f-4525-ae63-de58ee89db74"
}
Response Headers: 

HTTP/1.1 201
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Application-Context: application:8250
Accept-Ranges: none
Location: http://localhost:8250/vnflcm/v1/vnf_instances/14924fca-fb10-45da-bcf5-59c581d675d8
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 04 Jan 2018 12:18:13 GMT
Response Body (ETSI Data structure:VnfInstance)

{
    "_links": {
        "instantiate": {
            "href": "http://localhost:8250/vnflcm/v1/vnf_instances/14924fca-fb10-45da-bcf5-59c581d675d8/instantiate"
        },
        "self": {
            "href": "http://localhost:8250/vnflcm/v1/vnf_instances/14924fca-fb10-45da-bcf5-59c581d675d8"
        }
    },
    "id": "14924fca-fb10-45da-bcf5-59c581d675d8",
    "instantiationState": "NOT_INSTANTIATED",
    "onboardedVnfPkgInfoId": "vnfpkg-bb5601ef-cae8-4141-ba4f-e96b6cad0f74",
    "vnfInstanceName": "Test-VNf-Instance",
    "vnfProductName": "vnfd-1VDU",
    "vnfProvider": "",
    "vnfSoftwareVersion": "not-implemented",
    "vnfdId": "vnfd-88c6a03e-019f-4525-ae63-de58ee89db74",
    "vnfdVersion": ""
}

Instantiating Virtual Network Functions

The instantiation request triggers a number of message exchanges, which allows the call flow to be completed in order to instantiate a VNF instance. The resources are allocated when the VNF instance is instantiated. It requires the VNF instance identifier, returned by the create VNF request, encoded into the URL to which the request is posted.

The instatiation request sub-tasks within the flow include:

  1. Requesting permission from the NFVO (bi-directional Grant flow). For more information see, Requesting Grant Permission.

  2. Retrieving the VNF Descriptor template from the NFVO.

  3. Requesting the VNF resources to be allocated to the instance from the VIM.

Typically, the request permission, and retrieve messages are customized for the NFVO.

Method type: 
 POST
VNFM Endpoint: 
 /vnf_instances/{vnfInstanceId}/instantiate
HTTP Request Header: 
 Content-Type:application/json
Request Payload (ETSI data structure: InstantiateVNFRequest) 

{
    "flavourId": "vdu_node1",
    "extManagedVirtualLinks": [
        {
           "id": "esc-net",
            "resourceId": "RES1",
            "virtualLinkDescId": "VLD1"
        }
    ],
    "vimConnectionInfo": [
        {
            "accessInfo": {
                "resourceGroupId": "tenantName"
            },
            "id": "vimConnId",
            "vimType": "Openstack"
        }
    ]
}

The flavourId value must be same as the flavour_id specified in the VNFD file under properties.

Response Headers: 

HTTP/1.1 202
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Application-Context: application:8250
Accept-Ranges: none
Location: http://localhost:8250/vnflcm/v1/vnf_lcm_op_occs/457736f0-c877-4e07-8055-39dd406c616b
Content-Length: 0
Date: Thu, 04 Jan 2018 12:20:40 GMT
Response Body: 

not applicable.

You can customize the VNF before instantiation by adding variables to the VNFD template. Specify the variables in the additionalParams field of the LCM request. The variables are name-value pairs, where the value can be either string, numeric or boolean. In the example below, the cpus, and mem_size additionalParams are defined in the VNFD template.

Method type: 
 POST
VNFM Endpoint: 
 /vnf_instances/{vnfInstanceId}/instantiate
HTTP Request Header: 
 Content-Type:application/json
Request Payload (ETSI data structure: InstantiateVNFRequest) 

{
    "flavourId": "default",
    "additionalParams": {
        "cpus": 2,
        "mem_size": "512 MB"
    }
}'

When this template is submitted to the VNFM, the variables are merged into the same VNF instance.

The additionalParams variables are merged with the VNF variables, and actual values for the variables are provided only during instantiation.

The cpus, and mem_size variables are merged with the VNF variables in the example below. 

node_templates:
    my_server:
      type: tosca.nodes.Compute
      capabilities:
        host:
          properties:
            num_cpus: 2
            mem_size: 512 MB
            disk_size: 10 GB

If further LCM requests with additionalParams variables are submitted for the same VNF, then the new variables overwrite the existing variables. The VNFM uses the new variables for instantiation.


Note

The additional variables must be initially defined in the VNFD template, so that it can be used during instantiation, else the submission will fail.

ESC supports internal virtual links while instantiating a VNF using the TOSCA VNFD template.

Example for Virtual Internal Links from a TOSCA VNFD template:


   esc-test-net:
      type: tosca.nodes.nfv.VnfVirtualLinkDesc
      properties:
        connectivity_type:
          layer_protocol: ipv4
        description: VDU Internal Network VL

    EtsiTestInternalVL-Net-1:
      type: tosca.nodes.nfv.VnfVirtualLinkDesc
      properties:
        connectivity_type:
          layer_protocol: ipv4
        description: VDU Internal Network VL
        externally_managed: false

Requesting Grant Permission

The ETSI API requests for permission from the NFVO for lifecycle management operations to complete the operations in progress for the VNF instance resources. 

{
  "vnfInstanceId":"b9909dde-e21e-45ec-9cc0-9e9ae413eee0",
  "vnfLcmOpOccId":"d1409dde-f23e-61fh-9dc4-9e9eg667egb7",
  "vnfdId":"aaaaa-bbbb-1111-2222-cccc-1a3c5bb6543",
  "flavourId":"vanilla", /* not required? */
  "operation":"instantiate",
  "isAutomaticInvocation":"false", /* not required? */
  "instantiationLevelId":"admin", /* not required? */
  "addResources": {
      "":""
  }, /* not required? */
  "tempResources":"", /* not required? */
  "placementConstraints": {
      "affinityOrAntiAffinity":"ANTI_AFFINITY",
      "scope":"ZONE",
      "resource": {
          "idType":"GRANT",
          "resourceId":"myresourceid123"
      },
  }, /* not required? */
  "additionalParams": {
      "project":"tenant1"
  }, /* not required? */
  "links": {
      "vnfLcmOpOcc":"http://my-esc-vm:8250/vnf_lcm_op_occs/b9909dde-e21e-45ec-9cc0-9e9ae413eee2",
      "vnfInstance": "http://my-esc-vm:8250/vnflcm/v1/vnfinstances/b9909dde-e21e-45ec-9cc0-9e9ae413eee0"
  }
  "action": "instantiate"
}

Querying Virtual Network Functions

Querying VNFs does not affect the state of any VNF instance. This operation simply queries ESC for all the VNF instances it knows about, or a specific VNF isntance.

Method Type: 
 GET
VNFM Endpoint: 
 /vnf_instances
/vnf_instances/{vnfInstanceId}

Content-Type:application/merge-patch+json

ETag: "etag returned from Vnf Instance query"

 Content-Type:application/json
Request Payload: 
 not applicable.
Response Headers: 
 
< HTTP/1.1 200
HTTP/1.1 200
< X-Content-Type-Options: nosniff
X-Content-Type-Options: nosniff
< X-XSS-Protection: 1; mode=block
X-XSS-Protection: 1; mode=block
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
< Pragma: no-cache
Pragma: no-cache
< Expires: 0
Expires: 0
< X-Frame-Options: DENY
X-Frame-Options: DENY
< Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
< X-Application-Context: application:8250
X-Application-Context: application:8250
< Accept-Ranges: none
Accept-Ranges: none
< ETag: "2"
ETag: "2"
< Content-Type: application/json;charset=UTF-8
Content-Type: application/json;charset=UTF-8
< Transfer-Encoding: chunked
Transfer-Encoding: chunked
< Date: Thu, 04 Jan 2018 12:25:32 GMT
Date: Thu, 04 Jan 2018 12:25:32 GMT
Response Body for a single VNF Instance (ETSI Data structure:VnfInstance) 

{
    "_links": {
        "instantiate": {
            "href": "http://localhost:8250/vnflcm/v1/vnf_instances/14924fca-fb10-45da-bcf5-59c581d675d8/instantiate"
        },
        "self": {
            "href": "http://localhost:8250/vnflcm/v1/vnf_instances/14924fca-fb10-45da-bcf5-59c581d675d8"
        }
    },
    "id": "14924fca-fb10-45da-bcf5-59c581d675d8",
    "instantiationState": "NOT_INSTANTIATED",
    "onboardedVnfPkgInfoId": "vnfpkg-bb5601ef-cae8-4141-ba4f-e96b6cad0f74",
    "vnfInstanceName": "Test-VNf-Instance",
    "vnfProductName": "vnfd-1VDU",
    "vnfProvider": "",
    "vnfSoftwareVersion": "not-implemented",
    "vnfdId": "vnfd-88c6a03e-019f-4525-ae63-de58ee89db74",
    "vnfdVersion": ""
}
Response Body for all VNF Instances (ETSI Data structure:VnfInstance[]) 

{
    "_embedded": {
        "vnfInstances": [
            {
                "_links": {
                    "instantiate": {
                        "href": "http://localhost:8250/vnflcm/v1/vnf_instances/14924fca-fb10-45da-bcf5-59c581d675d8/instantiate"
                    },
                    "self": {
                        "href": "http://localhost:8250/vnflcm/v1/vnf_instances/14924fca-fb10-45da-bcf5-59c581d675d8"
                    }
                },
                "id": "14924fca-fb10-45da-bcf5-59c581d675d8",
                "instantiationState": "NOT_INSTANTIATED",
                "onboardedVnfPkgInfoId": "vnfpkg-bb5601ef-cae8-4141-ba4f-e96b6cad0f74",
                "vnfInstanceName": "Test-VNf-Instance",
                "vnfProductName": "vnfd-1VDU",
                "vnfProvider": "",
                "vnfSoftwareVersion": "not-implemented",
                "vnfdId": "vnfd-88c6a03e-019f-4525-ae63-de58ee89db74",
                "vnfdVersion": ""
            },
            {
                "_links": {
                    "instantiate": {
                        "href": "http://localhost:8250/vnflcm/v1/vnf_instances/9b82e224-2be5-44d8-821b-64ad7f4997fb/instantiate"
                    },
                    "self": {
                        "href": "http://localhost:8250/vnflcm/v1/vnf_instances/9b82e224-2be5-44d8-821b-64ad7f4997fb"
                    }
                },
                "id": "9b82e224-2be5-44d8-821b-64ad7f4997fb",
                "instantiationState": "NOT_INSTANTIATED",
                "onboardedVnfPkgInfoId": "vnfpkg-bb5601ef-cae8-4141-ba4f-e96b6cad0f74",
                "vnfInstanceName": "Test1-VNf-Instance",
                "vnfProductName": "vnfd-1VDU",
                "vnfProvider": "",
                "vnfSoftwareVersion": "not-implemented",
                "vnfdId": "vnfd-88c6a03e-019f-4525-ae63-de58ee89db74",
                "vnfdVersion": ""
            }
        ]
    },
    "_links": {
        "self": {
            "href": "http://localhost:8250/vnflcm/v1/vnf_instances"
        }
    }
}

The query VNF operation ouput shows the instantiated state of the VNF. The InstantiatedVnfInfo element shows the VIM resource information for all the VNFs.

Example


"instantiatedVnfInfo": {
                    "extCpInfo": [
                        {
                            "addresses": [
                                {
                                    "ipAddress": "172.16.253.27",
                                    "macAddress": "fa:16:3e:f3:68:6a"
                                }
                            ],
                            "cpdId": "node1_ecp",
                            "id": "extCp-4d6d9ea9-c159-4c4a-9f6b-b8305491a6bc"
                        }
                    ],

Modifying Virtual Network Functions

You can modify or update the properties of a VNF instance using the modify VNF lifecycle operation. ESC receives a PATCH request from NFVO to modify a single VNF instance.

A JSON merge algorithm is applied from the input payload against the stored data to modify the VNF instance.


Note

Modifying VNF operation updates only the properties, but not the functionality of the VNF.

The VNF is instantiated and deployed within ESC. The modify VNF operation does not affect the VIM.

The following properties of an existing VNF instance can be modified:

  • vnfInstanceName

  • vnfInstanceDescription

  • onboardedVnfPkgInfoId (null value is not allowed)

  • vnfConfigurableProperties

  • metadata

  • extensions

  • vimConnectionInfo

Method Type

PATCH

VNFM Endpoint

/vnf_instances/{vnfInstanceId}

HTTP Request Header

Content-Type:application/json

Request Payload(ETSI data structure: VnfInfoModifications)

{
    "vnfInstanceName": "My NEW VNF Instance Name",
    "vnfInstanceDescription": "My NEW VNF Instance Description",
    "vnfPkgId": "pkg-xyzzy-123",
    "vnfConfigurableProperties": {
        "isAutoscaleEnabled": "true"
    },
    "metadata": {
        "serialRange": "ab123-cc331",
        "manufacturer": "Cisco"
    },
    "extensions": {
        "testAccess": "false",
        "ipv6Interface": "false"
    },
    "vimConnectionInfo": [
        {
            "id": "vci1",
            "vimType": "openstack",
            "interfaceInfo": {
                "uri": "http://10.51.14.27:35357/v3"
            },
            "accessInfo": {
                "domainName": "default",
                "projectName": "admin",
                "userName": "default"
            }
        }
    ]
}

Response Header: NA

Response Body: NA

When the PATCH operation is complete, the VNF instance is modified, and the details are sent to the NFVO through the notification.

Operating Virtual Network Functions

You can start or stop a VNF instance using the operate lifecycle management operation. The VNF instance can be stopped gracefully or forcefully.


Note

The OpenStack API supports only forceful stop.

The changeStateTo field must have the value STARTED or STOPPED in the request payload, to start or stop a VNF instance.

Permission is also required from the NFVO (bi-directional Grant flow) for this operation. See Requesting Grant Permission for more informaiton.

Method Type: 
 POST
VNFM Endpoint: 
 /vnf_instances/{vnfInstanceId}/operate


HTTP Request Headers:

Content-Type:application/json

Request Payload: 
 
{
    "additionalParams": {
        "username": "user1"
    },
    "changeStateTo": "STOPPED",
    "stopType": "FORCEFUL"
}
Response Headers: 
 
HTTP/1.1 202
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: TEST
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Application-Context: application:8250
Accept-Ranges: none
Location: http://localhost:8250/vnflcm/v1/vnf_lcm_op_occs/e775aad5-8683-4450-b260-43656b6b13e9
Content-Length: 0
Date: Thu, 04 Jan 2018 12:40:27 GMT
Response Body: 
not applicable.

Terminating Virtual Network Functions

The terminating VNF request terminates a VNF instance. The resources are deallocated but remain reserved for this instance until it is deleted. Permission is required from the NFVO (bi-directional Grant flow) for this operation. The VNF instance can be decommissioned gracefully or forcefully.


Note

The OpenStack API supports only forceful termination.

As per the Instantiate VNF Request, the terminate VNF request requires the VNF instance identifier encoded into the URL to which the request is posted.

Method Type: 
 POST
VNFM Endpoint: 
/vnf_instances/{vnfInstanceId}/terminate
HTTP Request Headers: 
Content-Type:application/json
Request Payload (ETSI data structure: TerminateVnfRequest) 


{
  "terminationType":"FORCEFUL",
  "additionalParams": {
    "password": "pass1234",
    "username": "admin"
  }
}
Response Headers: 
 
HTTP/1.1 202
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: TEST
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Application-Context: application:8250
Accept-Ranges: none
Location: http://localhost:8250/vnflcm/v1/vnf_lcm_op_occs/dae25dbc-fcde-4ff9-8fd6-31797d19dbc1
Content-Length: 0
Date: Thu, 04 Jan 2018 12:45:59 GMT
Response Body: 
not applicable.

Deleting Virtual Network Functions

Deleting VNF operation releases the VIM resources reserved for the VNF instance as well as deletes the VNF instance identifier. Upon deletion, the VNF instance identifier is no longer available. So, no further lifecycle management operations are possible using this identifier.

Method Type: 
DELETE
VNFM Endpoint: 
/vnf_instances/{vnfInstanceId}
HTTP Request Headers: 
Content-Type:application/json
Request Payload: 
not applicable.
Response Headers: 
HTTP/1.1 204
HTTP/1.1 204
< X-Content-Type-Options: nosniff
X-Content-Type-Options: nosniff
< X-XSS-Protection: 1; mode=block
X-XSS-Protection: 1; mode=block
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
< Pragma: no-cache
Pragma: no-cache
< Expires: 0
Expires: 0
< X-Frame-Options: TEST
X-Frame-Options: TEST
< Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
< X-Application-Context: application:8250
X-Application-Context: application:8250
< Accept-Ranges: none
Accept-Ranges: none
< Date: Thu, 04 Jan 2018 12:48:59 GMT
Date: Thu, 04 Jan 2018 12:48:59 GMT
Response Body: 
not applicable.

Was this Document Helpful?

FeedbackFeedback

Contact Cisco