docs/user-guide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3 .. Copyright (C) 2021 Wind River Systems, Inc.
   4
   5 INF O2 Service User Guide
   6 =========================
   7
   8 This guide will introduce the process that make INF O2 interface work with
   9 SMO.
  10
  11 -  Assume you have an O2 service with INF platform environment
  12
  13    .. code:: bash
  14
  15       export OAM_IP=<INF_OAM_IP>
  16
  17 -  Discover INF platform inventory
  18
  19    -  INF platform auto discovery
  20
  21       After you installed the INF O2 service, it will automatically
  22       discover the INF through the parameters that you give from the
  23       “*o2service-override.yaml*”
  24
  25       Below command can get the INF platform information as O-Cloud
  26
  27       .. code:: shell
  28
  29          curl -X 'GET' \
  30            "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/" \
  31            -H 'accept: application/json'
  32
  33    -  Resource pool
  34
  35       One INF platform have one resource pool, all the resources that belong
  36       to this INF platform will be organized into this resource pool
  37
  38       Get the resource pool information through this interface
  39
  40       .. code:: shell
  41
  42          curl -X 'GET' \
  43            "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/resourcePools" \
  44            -H 'accept: application/json'
  45
  46          # export resource pool id
  47          export resourcePoolId=`curl -X 'GET'   "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/resourcePools"   -H 'accept: application/json' -H 'X-Fields: resourcePoolId' 2>/dev/null | jq .[].resourcePoolId | xargs echo`
  48
  49          echo ${resourcePoolId} # check the exported resource pool id
  50
  51    -  Resource type
  52
  53       Resource type defined what type is the specified resource, like a
  54       physical machine, memory, or CPU
  55
  56       Show all resource type
  57
  58       .. code:: shell
  59
  60          curl -X 'GET' \
  61            "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/resourceTypes" \
  62            -H 'accept: application/json'
  63
  64    -  Resource
  65
  66       Get the list of all resources, the value of *resourcePoolId* from
  67       the result of resource pool interface
  68
  69       .. code:: shell
  70
  71          curl -X 'GET' \
  72            "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/resourcePools/${resourcePoolId}/resources" \
  73            -H 'accept: application/json'
  74
  75       Get detail of one resource, need to export one specific resource
  76       id that wants to check
  77
  78       .. code:: shell
  79
  80          curl -X 'GET' \
  81            "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/resourcePools/${resourcePoolId}/resources/${resourceId}" \
  82            -H 'accept: application/json'
  83
  84    -  Deployment manager services endpoint
  85
  86       The Deployment Manager Service (DMS) that related to this IMS
  87       information you can use below API to check
  88
  89       .. code:: shell
  90
  91          curl -X 'GET' \
  92            "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/deploymentManagers" \
  93            -H 'accept: application/json'
  94
  95 -  Provisioning INF platform with SMO endpoint configuration
  96
  97    Assume you have an SMO, then configure INF platform with SMO endpoint
  98    address. This provisioning of INF O2 service will make a request from
  99    INF O2 service to SMO, that make SMO know the O2 service is working.
 100
 101    It needs SMO to have an API like
 102    “*http(s)://SMO_HOST:SMO_PORT/registration*”, which can accept JSON
 103    format data.
 104
 105    .. code:: bash
 106
 107       curl -X 'POST' \
 108         'http://'${OAM_IP}':30205/provision/v1/smo-endpoint' \
 109         -H 'accept: application/json' \
 110         -H 'Content-Type: application/json' \
 111         -d '{
 112         "endpoint": "http://<SMO_HOST>:<SMO_PORT>/registration"
 113       }'
 114
 115 -  Subscribe to the INF platform resource change notification
 116
 117    Assume you have an SMO, and the SMO have an API can be receive
 118    callback request
 119
 120    -  Create subscription in the INF O2 IMS
 121
 122       .. code:: bash
 123
 124          curl -X 'POST' \
 125            "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/subscriptions" \
 126            -H 'accept: application/json' \
 127            -H 'Content-Type: application/json' \
 128            -d '{
 129            "callback": "http://SMO/address/to/callback",
 130            "consumerSubscriptionId": "<ConsumerIdHelpSmoToIdentify>",
 131            "filter": "<ResourceTypeNameSplitByComma,EmptyToGetAll>"
 132          }'
 133
 134    -  Handle resource change notification
 135
 136       When the SMO callback API get the notification that the resource
 137       of INF platform changing, use the URL to get the latest resource
 138       information to update its database
 139
 140 -  Orchestrate CNF in helm chart
 141
 142    On this sample, we prepare a firewall chart to test the
 143    orchestration.
 144
 145    We need to do some preparation to make the helm repo work and include
 146    our firewall chart inside of the repository.
 147
 148       Get the DMS Id in the INF O2 service, and set it into bash environment
 149
 150       .. code:: bash
 151
 152          curl --location --request GET "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/deploymentManagers"
 153
 154          export dmsId=`curl --location --request GET "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/deploymentManagers" 2>/dev/null | jq .[].deploymentManagerId | xargs echo`
 155
 156          echo ${dmsId} # check the exported DMS id
 157
 158       Using helm to deploy a chartmuseum to the INF platform
 159
 160       .. code:: bash
 161
 162          helm repo add chartmuseum https://chartmuseum.github.io/charts
 163          helm repo update
 164          helm pull chartmuseum/chartmuseum # download chartmuseum-3.4.0.tgz to local
 165          tar zxvf chartmuseum-3.4.0.tgz
 166          cat <<EOF>chartmuseum-override.yaml
 167          env:
 168            open:
 169              DISABLE_API: false
 170          service:
 171            type: NodePort
 172            nodePort: 30330
 173          EOF
 174
 175          helm install chartmuseumrepo chartmuseum/chartmuseum -f chartmuseum-override.yaml
 176          kubectl get pods
 177          Kubectl get services
 178
 179       Update the helm repo and add the chartmusem into the repository
 180
 181       .. code:: bash
 182
 183          helm repo add o2imsrepo http://${NODE_IP}:30330
 184          helm repo update
 185
 186       Download the firewall chart and push it into the repository
 187
 188       .. code:: bash
 189
 190          git clone https://github.com/biny993/firewall-host-netdevice.git
 191          tar -zcvf firewall-host-netdevice-1.0.0.tgz firewall-host-netdevice/
 192          helm plugin install https://github.com/chartmuseum/helm-push.git
 193          helm cm-push firewall-host-netdevice-1.0.0.tgz o2imsrepo
 194          helm repo update
 195          helm search repo firewall
 196
 197       Setup host net device over INF node
 198
 199       .. code:: bash
 200
 201          ssh sysadmin@<INF OAM IP>
 202          sudo ip link add name veth11 type veth peer name veth12
 203          sudo ip link add name veth21 type veth peer name veth22
 204          sudo ip link |grep veth
 205          exit
 206
 207    -  Create NfDeploymentDescriptor on the INF O2 DMS
 208
 209       .. code:: bash
 210
 211          curl --location --request POST "http://${OAM_IP}:30205/o2dms/v1/${dmsId}/O2dms_DeploymentLifecycle/NfDeploymentDescriptor" \
 212          --header 'Content-Type: application/json' \
 213          --data-raw '{
 214            "name": "cfwdesc1",
 215            "description": "demo nf deployment descriptor",
 216            "artifactRepoUrl": "http://'${NODE_IP}':30330",
 217            "artifactName": "firewall-host-netdevice",
 218            "inputParams":
 219            "{\n  \"image\": {\n    \"repository\": \"ubuntu\",\n    \"tag\": 18.04,\n    \"pullPolicy\": \"IfNotPresent\"\n  },\n  \"resources\": {\n    \"cpu\": 2,\n    \"memory\": \"2Gi\",\n    \"hugepage\": \"0Mi\",\n    \"unprotectedNetPortVpg\": \"veth11\",\n    \"unprotectedNetPortVfw\": \"veth12\",\n    \"unprotectedNetCidr\": \"10.10.1.0/24\",\n    \"unprotectedNetGwIp\": \"10.10.1.1\",\n    \"protectedNetPortVfw\": \"veth21\",\n    \"protectedNetPortVsn\": \"veth22\",\n    \"protectedNetCidr\": \"10.10.2.0/24\",\n    \"protectedNetGwIp\": \"10.10.2.1\",\n    \"vfwPrivateIp0\": \"10.10.1.1\",\n    \"vfwPrivateIp1\": \"10.10.2.1\",\n    \"vpgPrivateIp0\": \"10.10.1.2\",\n    \"vsnPrivateIp0\": \"10.10.2.2\"\n  }\n}",
 220            "outputParams": "{\"output1\": 100}"
 221          }'
 222
 223          curl --location --request GET "http://${OAM_IP}:30205/o2dms/v1/${dmsId}/O2dms_DeploymentLifecycle/NfDeploymentDescriptor"
 224
 225          export descId=` curl -X 'GET'   "http://${OAM_IP}:30205/o2dms/v1/${dmsId}/O2dms_DeploymentLifecycle/NfDeploymentDescriptor"   -H 'accept: application/json'   -H 'X-Fields: id' 2>/dev/null | jq .[].id | xargs echo`
 226
 227          echo ${descId} # check the exported descriptor id
 228
 229    -  Create NfDeployment on the INF O2 DMS
 230
 231       When you have an descriptor of deployment, you can create a
 232       NfDeployment, it will trigger an event inside of the IMS/DMS, and
 233       use the K8S API to create a real pod of the firewall sample
 234
 235       .. code:: bash
 236
 237          curl --location --request POST "http://${OAM_IP}:30205/o2dms/v1/${dmsId}/O2dms_DeploymentLifecycle/NfDeployment" \
 238          --header 'Content-Type: application/json' \
 239          --data-raw '{
 240            "name": "cfw100",
 241            "description": "demo nf deployment",
 242            "descriptorId": "'${descId}'",
 243            "parentDeploymentId": ""
 244          }'
 245
 246          curl --location --request GET "http://${OAM_IP}:30205/o2dms/v1/${dmsId}/O2dms_DeploymentLifecycle/NfDeployment"
 247
 248    -  Check pods of the firewall sample
 249
 250       .. code:: bash
 251
 252          kubectl get pods
 253
 254    -  Delete the deployment we just created
 255
 256       .. code:: shell
 257
 258          export NfDeploymentId=`curl --location --request GET "http://${OAM_IP}:30205/o2dms/v1/${dmsId}/O2dms_DeploymentLifecycle/NfDeployment" 2>/dev/null | jq .[].id | xargs echo`
 259
 260          echo ${NfDeploymentId} # Check the exported deployment id
 261
 262          curl --location --request DELETE "http://${OAM_IP}:30205/o2dms/v1/${dmsId}/O2dms_DeploymentLifecycle/NfDeployment/${NfDeploymentId}"