vCPE Homing Use Case

This document describes the Homing Template Specifications for residential vCPE. It is a work in progress and subject to frequent revision.

vCPE Service Model


Homing Policies and information sources relevant to the policies

vCPEPoliciesAndInformationSources


Homing Workflow


SO - HAS API (R) - before retrieving homing policies

SO - HAS API (R)
requestInfo:
  callbackUrl: https://so:5000/callback
  numSolutions: 1
  optimizer:
  - placement
  requestId: yyy-yyy-yyyy
  sourceId: so
  timeout: 600
  transactionId: xxx-xxx-xxxx
  requestType: new
placementInfo:
  orderInfo:
    requestParameters:
      customerLatitude: 32.897480
      customerLongitude: -97.040443
      customerName: some_company
  demandInfo:
    placementDemands:
    - resourceName: vGMuxInfra
      resourceId: some_resource_id
      tenantId: some_tenant_id
      resourceModelInfo:
        modelId: vGMux_model_id
        modelName: ''
        modelType: allotted
        modelVersion: '2.0'
      existingPlacement:
        serviceInstanceId: 87257b49-9602-4ca1-9817-094e52bc873b
      excludedCandidates:
      - candidateType: service
        candidates:
        - serviceInstanceId: 1ac71fb8-ad43-4e16-9459-c3f372b8236d
      requiredCandidates:
      - candidateType: service 
        candidates:
        - serviceInstanceId: 7e6c3e57-62cd-44f6-aa88-d0896998f7ec
    - resourceName: vG
      tenantId: some_tenant_id
      resourceId: 71d563e8-e714-4393-8f99-cc480144a05e
      resourceModelInfo:
        modelId: vG_model_id
        modelName: ''
        modelType: dedicated
        modelVersion: '2.0'
      existingPlacement:
        serviceInstanceId: 21d5f3e8-e714-4383-8f99-cc480144505a
      excludedCandidates:
      - candidateType: service
        candidates:
        - serviceInstanceId: 1ac71fb8-ad43-4e16-9459-c3f372b8236d
      requiredCandidates:
      - candidateType: cloud
        candidates:
        - cloud-region-id: TXAUS219

  otherInfo:
    serviceInstanceId: d61b2543-5914-4b8f-8e81-81e38575b8ec
  serviceModelInfo:
    serviceName: Residential vCPE
    service_id: vcpe_service_id
    serviceType: service
    serviceVersion: '1.0'


HAS Homing Specification (R') - after retrieving and translating homing policies

vCPE Homing Template (JSON)
{
  "homing_template_version": "2017-10-10",
  "parameters": {
    "service_name": "Residential vCPE",
    "service_id": "vcpe_service_id",
    "customer_lat": 32.89748,
    "customer_long": -97.040443,
    "REQUIRED_MEM": 4,
    "REQUIRED_DISK": 100
  },
  "locations": {
    "customer_loc": {
      "latitude": {
        "get_param": "customer_lat"
      },
      "longitude": {
        "get_param": "customer_long"
      }
    }
  },
  "demands": {
    "vGMuxInfra": [
      {
        "inventory_provider": "aai",
        "inventory_type": "service",
        "attributes": {
          "equipment_type": "vG_Mux",
          "customer_id": "some_company"
        },
        "excluded_candidates": [
          {
            "candidate_id": "1ac71fb8-ad43-4e16-9459-c3f372b8236d"
          }
        ],
        "existing_placement": [
          {
            "candidate_id": "21d5f3e8-e714-4383-8f99-cc480144505a"
          }
        ]
      }
    ],
    "vG": [
      {
        "inventory_provider": "aai",
        "inventory_type": "cloud"
      }
    ]
  },
  "constraints": {
    "constraint_vgmux_customer": {
      "type": "distance_to_location",
      "demands": [
        "vGMuxInfra"
      ],
      "properties": {
        "distance": "< 100 km",
        "location": "customer_loc"
      }
    },
    "colocation": {
      "type": "zone",
      "demands": [
        "vGMuxInfra",
        "vG"
      ],
      "properties": {
        "qualifier": "same",
        "category": "region"
      }
    },
    "hpa_constraint": {
      "type": "hpa",
      "demands": [
        "vG"
      ],
      "properties": {
        "evaluate": [
          {
            "flavorLabel": "flavor_label_1",
            "flavorProperties": [
              {
                "hpa-feature": "basicCapabilities",
                "hpa-version": "v1",
                "architecture": "generic",
                "hpa-feature-attributes": [
                  {
                    "hpa-attribute-key": "numVirtualCpu",
                    "hpa-attribute-value": "4",
                    "operator": "="
                  },
                  {
                    "hpa-attribute-key": "virtualMemSize",
                    "hpa-attribute-value": "4",
                    "operator": "=",
                    "unit": "GB"
                  }
                ]
              },
              {
                "hpa-feature": "numa",
                "hpa-version": "v1",
                "architecture": "generic",
                "hpa-feature-attributes": [
                  {
                    "hpa-attribute-key": "numaNodes",
                    "hpa-attribute-value": "2",
                    "operator": "="
                  },
                  {
                    "hpa-attribute-key": "numaCpu-0",
                    "hpa-attribute-value": "2",
                    "operator": "="
                  },
                  {
                    "hpa-attribute-key": "numaCpu-1",
                    "hpa-attribute-value": "4",
                    "operator": "="
                  },
                  {
                    "hpa-attribute-key": "numaMem-0",
                    "hpa-attribute-value": "2",
                    "operator": "=",
                    "unit": "GB"
                  },
                  {
                    "hpa-attribute-key": "numaMem-1",
                    "hpa-attribute-value": "4",
                    "operator": "=",
                    "unit": "GB"
                  }
                ]
              },
              {
                "hpa-feature": "cpuPinning",
                "hpa-version": "v1",
                "architecture": "generic",
                "hpa-feature-attributes": [
                  {
                    "hpa-attribute-key": "logicalCpuThreadPinningPolicy",
                    "hpa-attribute-value": "prefer",
                    "operator": "="
                  },
                  {
                    "hpa-attribute-key": "logicalCpuPinningPolicy",
                    "hpa-attribute-value": "dedicated",
                    "operator": "="
                  }
                ]
              }
            ]
          },
          {
            "flavorLabel": "flavor_label_2",
            "flavorProperties": [
              {
                "hpa-feature": "basicCapabilities",
                "hpa-version": "v1",
                "architecture": "generic",
                "hpa-feature-attributes": [
                  {
                    "hpa-attribute-key": "numVirtualCpu",
                    "hpa-attribute-value": "8",
                    "operator": "="
                  },
                  {
                    "hpa-attribute-key": "virtualMemSize",
                    "hpa-attribute-value": "16",
                    "operator": "=",
                    "unit": "GB"
                  }
                ]
              },
              {
                "hpa-feature": "numa",
                "hpa-version": "v1",
                "architecture": "generic",
                "hpa-feature-attributes": [
                  {
                    "hpa-attribute-key": "numaNodes",
                    "hpa-attribute-value": "2",
                    "operator": "="
                  },
                  {
                    "hpa-attribute-key": "numaCpu-0",
                    "hpa-attribute-value": "2",
                    "operator": "="
                  },
                  {
                    "hpa-attribute-key": "numaCpu-1",
                    "hpa-attribute-value": "4",
                    "operator": "="
                  },
                  {
                    "hpa-attribute-key": "numaMem-0",
                    "hpa-attribute-value": "2",
                    "operator": "=",
                    "unit": "GB"
                  },
                  {
                    "hpa-attribute-key": "numaMem-1",
                    "hpa-attribute-value": "4",
                    "operator": "=",
                    "unit": "GB"
                  }
                ]
              },
              {
                "hpa-feature": "memoryPageSize",
                "hpa-version": "v1",
                "architecture": "generic",
                "hpa-feature-attributes": [
                  {
                    "hpa-attribute-key": "memoryPageSize",
                    "hpa-attribute-value": "2",
                    "operator": "=",
                    "unit": "GB"
                  }
                ]
              }
            ]
          }
        ]
      }
    },
    "check_cloud_capacity": {
      "type": "vim_fit",
      "demands": [
        "vG"
      ],
      "properties": {
        "controller": "multicloud",
        "request": {
          "vCPU": 10,
          "Memory": {
            "quantity": {
              "get_param": "REQUIRED_MEM"
            },
            "unit": "GB"
          },
          "Storage": {
            "quantity": {
              "get_param": "REQUIRED_DISK"
            },
            "unit": "GB"
          }
        }
      }
    }
  },
  "optimization": {
    "minimize": {
      "sum": [
        {
          "distance_between": [
            "customer_loc",
            "vGMuxInfra"
          ]
        },
        {
          "distance_between": [
            "customer_loc",
            "vG"
          ]
        }
      ]
    }
  }
}



vCPE Homing Template (YAML)
---
homing_template_version: '2017-10-10'
parameters:
  service_name: Residential vCPE
  service_id: vcpe_service_id
  customer_lat: 32.89748
  customer_long: -97.040443
  REQUIRED_MEM: 4
  REQUIRED_DISK: 100
locations:
  customer_loc:
    latitude:
      get_param: customer_lat
    longitude:
      get_param: customer_long
demands:
  vGMuxInfra:
  - inventory_provider: aai
    inventory_type: service
    attributes:
      equipment_type: vG_Mux
      customer_id: some_company
    excluded_candidates:
    - candidate_id: 1ac71fb8-ad43-4e16-9459-c3f372b8236d
    existing_placement:
    - candidate_id: 21d5f3e8-e714-4383-8f99-cc480144505a
  vG:
  - inventory_provider: aai
    inventory_type: cloud
constraints:
  constraint_vgmux_customer:
    type: distance_to_location
    demands:
    - vGMuxInfra
    properties:
      distance: "< 100 km"
      location: customer_loc
  colocation:
    type: zone
    demands:
    - vGMuxInfra
    - vG
    properties:
      qualifier: same
      category: region
  hpa_constraint:
    type: hpa
    demands:
    - vG
    properties:
      evaluate:
      - flavorLabel: flavor_label_1
        flavorProperties:
        - hpa-feature: basicCapabilities
          hpa-version: v1
          architecture: generic
          hpa-feature-attributes:
          - hpa-attribute-key: numVirtualCpu
            hpa-attribute-value: '4'
            operator: "="
          - hpa-attribute-key: virtualMemSize
            hpa-attribute-value: '4'
            operator: "="
            unit: GB
        - hpa-feature: numa
          hpa-version: v1
          architecture: generic
          hpa-feature-attributes:
          - hpa-attribute-key: numaNodes
            hpa-attribute-value: '2'
            operator: "="
          - hpa-attribute-key: numaCpu-0
            hpa-attribute-value: '2'
            operator: "="
          - hpa-attribute-key: numaCpu-1
            hpa-attribute-value: '4'
            operator: "="
          - hpa-attribute-key: numaMem-0
            hpa-attribute-value: '2'
            operator: "="
            unit: GB
          - hpa-attribute-key: numaMem-1
            hpa-attribute-value: '4'
            operator: "="
            unit: GB
        - hpa-feature: cpuPinning
          hpa-version: v1
          architecture: generic
          hpa-feature-attributes:
          - hpa-attribute-key: logicalCpuThreadPinningPolicy
            hpa-attribute-value: prefer
            operator: "="
          - hpa-attribute-key: logicalCpuPinningPolicy
            hpa-attribute-value: dedicated
            operator: "="
      - flavorLabel: flavor_label_2
        flavorProperties:
        - hpa-feature: basicCapabilities
          hpa-version: v1
          architecture: generic
          hpa-feature-attributes:
          - hpa-attribute-key: numVirtualCpu
            hpa-attribute-value: '8'
            operator: "="
          - hpa-attribute-key: virtualMemSize
            hpa-attribute-value: '16'
            operator: "="
            unit: GB
        - hpa-feature: numa
          hpa-version: v1
          architecture: generic
          hpa-feature-attributes:
          - hpa-attribute-key: numaNodes
            hpa-attribute-value: '2'
            operator: "="
          - hpa-attribute-key: numaCpu-0
            hpa-attribute-value: '2'
            operator: "="
          - hpa-attribute-key: numaCpu-1
            hpa-attribute-value: '4'
            operator: "="
          - hpa-attribute-key: numaMem-0
            hpa-attribute-value: '2'
            operator: "="
            unit: GB
          - hpa-attribute-key: numaMem-1
            hpa-attribute-value: '4'
            operator: "="
            unit: GB
        - hpa-feature: memoryPageSize
          hpa-version: v1
          architecture: generic
          hpa-feature-attributes:
          - hpa-attribute-key: memoryPageSize
            hpa-attribute-value: '2'
            operator: "="
            unit: GB
  check_cloud_capacity: 
    type: vim_fit
    demands:
    - vG
    properties:
      controller: multicloud
      request:
        vCPU: 10
        Memory:
          quantity:
            get_param: REQUIRED_MEM
          unit: GB
        Storage:
          quantity:
            get_param: REQUIRED_DISK
          unit: GB
optimization:
  minimize:
    sum:
    - distance_between:
      - customer_loc
      - vGMuxInfra
    - distance_between:
      - customer_loc
      - vG




HAS Homing Response

State - Done

vCPE homing response (JSON)
{
  "plans": [
    {
      "status": "done",
      "id": "plan_id",
      "name": "Plan Name 1",
      "links": [
        [
          {
            "href": "http://conductor:8091/v1/plans/plan_id",
            "rel": "self"
          }
        ]
      ],
      "recommendations": [
        {
          "vG": {
            "inventory_provider": "aai",
            "candidate": {
              "candidate_id": "DLLSTX1A",
              "cloud_owner": "CloudOwner1",
              "inventory_type": "cloud",
              "location_id": "DLLSTX1A",
              "location_type": "openstack-cloud"
            },
            "attributes": {
              "flavors": {
                "flavor_label_1": "vim_flavor_X",
                "flavor_label_2": "vim_flavor_Y"
              },
              "cloud_owner": "CloudOwner1",
              "physical-location-id": "DLLSTX1A",
              "cloud_version": "3.0",
			  "vim-id": "CloudOwner1_DLLSTX1A"
            }
          }
        },
        {
          "vGMuxInfra": {
            "attributes": {
              "host_id": "vgmux_host_name",
              "cloud_owner": "CloudOwner1",
              "physical-location-id": "DLLSTX1A",
              "service_instance_id": "21d5f3e8-e714-4383-8f99-cc480144505a",
              "cloud_version": "3.0",
			  "vim-id": "CloudOwner1_DLLSTX1A"
            },
            "inventory_provider": "aai",
            "service_resource_id": "12345",
            "candidate": {
              "is_rehome": "false",
              "location_id": "DLLSTX1A",
              "inventory_type": "service",
              "candidate_id": "21d5f3e8-e714-4383-8f99-cc480144505a",
              "host_id": "vgmux_host_name",
              "cloud_owner": "CloudOwner1",
              "location_type": "openstack-cloud"
            }
          }
        }
      ]
    }
  ]
}


State - Error 

HAS Error Response
{
  "plans": [
    {
      "status": "error",
      "message": "Some error message",
      "name": "Plan Name 1",
      "links": [
        [
          {
            "href": "http://conductor:8091/v1/plans/plan_id",
            "rel": "self"
          }
        ]
      ],
      "id": "plan_id"
    }
  ]
}


State - Template 

HAS Plan in Template State
{
  "status": "template",
  "name": "Plan Name 1",
  "links": [
    [
      {
        "href": "http://conductor:8091/v1/plans/plan_id",
        "rel": "self"
      }
    ]
  ],
  "id": "plan_id"
}


State - Solving

HAS Plan in Solving state
{
  "plans": [
    {
      "status": "solving",
      "name": "Plan Name 1",
      "links": [
        [
          {
            "href": "http://conductor:8091/v1/plans/plan_id",
            "rel": "self"
          }
        ]
      ],
      "id": "plan_id"
    }
  ]
}



  • No labels

19 Comments

  1. Shankaranarayanan Puzhavakath Narayanan:

    Can you please also add the conductor response structure here?

    1. Ankitkumar Patel :

      Could you please verify if the response from HAS is fine?

      1. Hi Shankar and Dileep,

        Based on the API specs, the conductor response is translated into the following response to SO. Why a cloud_owner is mentioned twice in the VG solution? Can you please verify the flavor details are captured correctly in the following response?


        {
          "transactionId""xxx-xxx-xxxx",
          "requestId""yyy-yyy-yyyy",
          "requestStatus""completed",
          "statusMessage""",
          "solutions": {
            "placementSolutions": [
             [
              {
                "resourceModuleName""vGMuxInfra",
                "serviceResourceId": "<copy from Req.>",
                "solution": {
                    "identifierType""serviceInstanceId",
                    "identifiers": ["21d5f3e8-e714-4383-8f99-cc480144505a"]
                },
                "assignmentInfo": [
                  "key""cloud_owner""value""rackspace" },
                  "key""host_id""value""vgmux_host_name" },
                  "key""is_rehome""value""false" },
                  "key""location_id""value""DLLSTX1A" },

                              "key""location_type""value""openstack-cloud" },

                              "key""vim-id""value""rackspace_DLLSTX1A" },

                              "key""physical-location-id""value""DLLSTX1223" }
                ]
              },
              {
                "resourceModuleName""vG",
                "serviceResourceId""<copy from Req.>",
                "solution": {
                    "identifierType""cloudRegionId",
                    "cloudOwner""rackspace",
                    "identifiers": ["DLLSTX1A"]
                },
                "assignmentInfo": [
                  "key""is_rehome""value""false" },
                  "key""location_id""value""DLLSTX1A" },

                              "key""location_type""value""openstack-cloud" },

                              "key""vim-id""value""rackspace_DLLSTX1A" },

                               "key""physical-location-id""value""DLLSTX1223" },

                               "key""flavor_label_1""value""vim_flavor_X" },

                               "key""flavor_label_2""value""vim_flavor_Y" }
                ]
              }
             ]
            ],

                ...

           }

        }

        1. Hi Ankit, This is much closer to what I was expecting (what my code reflects based on the API spec, whew!).

          I agree with Dileep suggestion of formatting in the following way:

          "key":"flavors",

                "value":{ 

                   "flavorLabel1xxx":"vimFlavorxxx",

                   "flavorLabel2xxx":"vim_flavorxxx"


                }


          A few nits, otherwise. We should conform the formatting to camelCase as we have in the rest of the API, so I'd expect something closer to the following (granted there are places where keys are arbitrary and the value will change). If the following is agreeable and correct can we add this to API spec?

          {  
             "transactionId":"xxx-xxx-xxxx",
             "requestId":"yyy-yyy-yyyy",
             "requestStatus":"completed",
             "statusMessage":"",
             "solutions":{  
                "placementSolutions":[  
                   [  
                      {  
                         "resourceModuleName":"vGMuxInfra",
                         "serviceResourceId":"<copy from Req.>",
                         "solution":{  
                            "identifierType":"serviceInstanceId",
                            "identifiers":[  
                               "21d5f3e8-e714-4383-8f99-cc480144505a"
                            ]
                         },
                         "assignmentInfo":[  
                            {  
                               "key":"cloudOwner",
                               "value":"rackspace"
                            },
                            {  
                               "key":"hostId",
                               "value":"vgmux_host_name"
                            },
                            {  
                               "key":"isRehome",
                               "value":"false"
                            },
                            {  
                               "key":"locationId",
                               "value":"DLLSTX1A"
                            },
                            {  
                               "key":"locationType",
                               "value":"openstack-cloud"
                            },
                            {  
                               "key":"vimId",
                               "value":"rackspace_DLLSTX1A"
                            },
                            {  
                               "key":"physicalLocationId",
                               "value":"DLLSTX1223"
                            }
                         ]
                      },
                      {  
                         "resourceModuleName":"vG",
                         "serviceResourceId":"<copy from Req.>",
                         "solution":{  
                            "identifierType":"cloudRegionId",
                            "cloudOwner":"rackspace",
                            "identifiers":[  
                               "DLLSTX1A"
                            ]
                         },
                         "assignmentInfo":[  
                            {  
                               "key":"isRehome",
                               "value":"false"
                            },
                            {  
                               "key":"locationId",
                               "value":"DLLSTX1A"
                            },
                            {  
                               "key":"locationType",
                               "value":"openstack-cloud"
                            },
                            {  
                               "key":"vimId",
                               "value":"rackspace_DLLSTX1A"
                            },
                            {  
                               "key":"physicalLocationId",
                               "value":"DLLSTX1223"
                            },
                            {

                               "key":"flavors",


                               "value":{ 

                                  "flavorLabel1xxx":"vimFlavorxxx",

                                  "flavorLabel2xxx":"vimFlavorxxx"


                               }

                            }

                         ]
                      }
                   ]
                ],
                ...
             }
          }


          Srini, Any comments?

          Thanks Marcus.

          1. I am fine with the proposal. These changes can be easily captured in the SO response based on the current API specs.

  2. This

    "

    "key":"flavors",


                         "value":{ 

                            "flavorLabel1xxx":"vimFlavorxxx",

                            "flavorLabel2xxx":"vimFlavorxxx

    "

    looks good to me.

  3. Ankitkumar Patel , for the HAS Homing Specification (R'), the flavor_label_1 is got from Policy , and is it uploaded by manually ? will there be a same one stored in A&AI?

          - label: flavor_label_1

    1. Hi libo zhu,

      In R2, the HPA policies will be manually created. Once the policy system interfaces with SDC, the HPA policies can be auto-populated. So, flavor labels must be manually populated in the HPA policies and they must match in A&AI too.

      Ankit

  4. Shankaranarayanan Puzhavakath Narayanan and Matti Hiltunen:

    The HAS interface is of type polling, correct? What are the different states a solver can be? Can you please capture the compete JSON body of a conductor response here? Also, what should be the waiting time prior to returning a failure message to SO?

    Ankit

    1. Ankit, I've mocked up a few sample responses for the different HAS states. Ikram Ikramullah can confirm if these are indeed correct. 

  5. Hi Ankitkumar,

    I have small queries - 

    1. "SO - HAS API (R) - before retrieving homing policies" -  Is what SO sends to "Optimization Service Design Framework" as request input?

    2. "HAS Homing Specification (R') - after retrieving and translating homing policies"   -  is what "Optimization Service Design Framework" sends to HAS after evaluating the request against policies?

    3. "HAS Homing Response" - is what HAS sends back to SO(via OSDF)?

    Am I correct?

    1. Chittaranjan Sardar, The first two are absolutely correct. The third is the response HAS sends back to OSDF. However, there is a minor massaging of the response by OSDF before returning the homing recommendation back to SO. 

      1. Hi Shankaranarayanan,

        I got it.
        Can we have a look on how will be the Final Structure of the final out put to SO(from OSDF, as you mentioned, after final massaging)?
        or link/s to documentation will be great.

  6. Folks, I've updated the vCPE template based on the recent developments. 

    • The customer location was hardcoded in SNIRO emulator in R1. In R2, we were hoping to get the customer location through the location of the BRG from AAI. However, it looks like this will continue to be an order parameter that is hard-coded in the homing request from SO/OSDF. Hence, we should remove the pnf_location section from the locations.  
    • Removed the min_guarantee_capability constraint, since we moved it to R2.+ given that it needs to be aligned with the HPA constraints, and since it needs support from AAI for changes to cloud region schema
    • Made minor edits to the key:value pairs to align with the MultiCloud API. 
  7. Dileep Ranganathan and Shankaranarayanan Puzhavakath Narayanan:

    The hpa constraint in the conductor template example contains different attribute names than the hpa policy model. For example, 'label' should be changed to 'flavorLabel' and 'feature' should be changed to 'flavorProperties'. Can you please update the conductor template and make it compliant with the hpa policy model? 

    Thanks,

    Ankit

    1. Dileep RanganathanAnkitkumar Patel - Made the suggested edits to the template. Please check and let me know if this is what you had in mind. 

  8. Dileep Ranganathan and Shankaranarayanan Puzhavakath Narayanan


    The conductor response should contain serviceResourceId that is sent in a request. I think, SO used the id to map the solution to demands.


    Ankit

    1. That's correct - the response should have the service resource id (State-Done)