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-2022 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
   9 with 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
  36       belong to this INF platform will be organized into this resource
  37       pool
  38
  39       Get the resource pool information through this interface
  40
  41       .. code:: shell
  42
  43          curl -X 'GET' \
  44            "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/resourcePools" \
  45            -H 'accept: application/json'
  46
  47          # export resource pool id
  48          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`
  49
  50          echo ${resourcePoolId} # check the exported resource pool id
  51
  52    -  Resource type
  53
  54       Resource type defined what type is the specified resource, like a
  55       physical machine, memory, or CPU
  56
  57       Show all resource type
  58
  59       .. code:: shell
  60
  61          curl -X 'GET' \
  62            "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/resourceTypes" \
  63            -H 'accept: application/json'
  64
  65    -  Resource
  66
  67       Get the list of all resources, the value of *resourcePoolId* from
  68       the result of resource pool interface
  69
  70       .. code:: shell
  71
  72          curl -X 'GET' \
  73            "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/resourcePools/${resourcePoolId}/resources" \
  74            -H 'accept: application/json'
  75
  76       Get detail of one resource, need to export one specific resource
  77       id that wants to check
  78
  79       .. code:: shell
  80
  81          curl -X 'GET' \
  82            "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/resourcePools/${resourcePoolId}/resources/${resourceId}" \
  83            -H 'accept: application/json'
  84
  85    -  Deployment manager services endpoint
  86
  87       The Deployment Manager Service (DMS) that related to this IMS
  88       information you can use below API to check
  89
  90       .. code:: shell
  91
  92          curl -X 'GET' \
  93            "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/deploymentManagers" \
  94            -H 'accept: application/json'
  95
  96 -  Provisioning INF platform with SMO endpoint configuration
  97
  98    Assume you have an SMO, then configure INF platform with SMO endpoint
  99    address. This provisioning of INF O2 service will make a request from
 100    INF O2 service to SMO, that make SMO know the O2 service is working.
 101
 102    It needs SMO to have an API like
 103    “*http(s)://SMO_HOST:SMO_PORT/registration*”, which can accept JSON
 104    format data.
 105
 106    .. code:: bash
 107
 108       curl -X 'POST' \
 109         'http://'${OAM_IP}':30205/provision/v1/smo-endpoint' \
 110         -H 'accept: application/json' \
 111         -H 'Content-Type: application/json' \
 112         -d '{
 113         "endpoint": "http://<SMO_HOST>:<SMO_PORT>/registration"
 114       }'
 115
 116 -  Subscribe to the INF platform resource change notification
 117
 118    Assume you have an SMO, and the SMO have an API can be receive
 119    callback request
 120
 121    -  Create subscription in the INF O2 IMS
 122
 123       .. code:: bash
 124
 125          curl -X 'POST' \
 126            "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/subscriptions" \
 127            -H 'accept: application/json' \
 128            -H 'Content-Type: application/json' \
 129            -d '{
 130            "callback": "http://SMO/address/to/callback",
 131            "consumerSubscriptionId": "<ConsumerIdHelpSmoToIdentify>",
 132            "filter": "<ResourceTypeNameSplitByComma,EmptyToGetAll>"
 133          }'
 134
 135    -  Handle resource change notification
 136
 137       When the SMO callback API get the notification that the resource
 138       of INF platform changing, use the URL to get the latest resource
 139       information to update its database
 140
 141 -  Orchestrate CNF in helm chart
 142
 143    On this sample, we prepare a firewall chart to test the
 144    orchestration.
 145
 146    We need to do some preparation to make the helm repo work and include
 147    our firewall chart inside of the repository.
 148
 149       Get the DMS Id in the INF O2 service, and set it into bash
 150       environment
 151
 152       .. code:: bash
 153
 154          curl --location --request GET "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/deploymentManagers"
 155
 156          export dmsId=`curl --location --request GET "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/deploymentManagers" 2>/dev/null | jq .[].deploymentManagerId | xargs echo`
 157
 158          echo ${dmsId} # check the exported DMS id
 159
 160       Using helm to deploy a chartmuseum to the INF platform
 161
 162       .. code:: bash
 163
 164          helm repo add chartmuseum https://chartmuseum.github.io/charts
 165          helm repo update
 166          helm pull chartmuseum/chartmuseum # download chartmuseum-3.4.0.tgz to local
 167          tar zxvf chartmuseum-3.4.0.tgz
 168          cat <<EOF>chartmuseum-override.yaml
 169          env:
 170            open:
 171              DISABLE_API: false
 172          service:
 173            type: NodePort
 174            nodePort: 30330
 175          EOF
 176
 177          helm install chartmuseumrepo chartmuseum/chartmuseum -f chartmuseum-override.yaml
 178          kubectl get pods
 179          Kubectl get services
 180
 181       Update the helm repo and add the chartmusem into the repository
 182
 183       .. code:: bash
 184
 185          helm repo add o2imsrepo http://${NODE_IP}:30330
 186          helm repo update
 187
 188       Download the firewall chart and push it into the repository
 189
 190       .. code:: bash
 191
 192          git clone https://github.com/biny993/firewall-host-netdevice.git
 193          tar -zcvf firewall-host-netdevice-1.0.0.tgz firewall-host-netdevice/
 194          helm plugin install https://github.com/chartmuseum/helm-push.git
 195          helm cm-push firewall-host-netdevice-1.0.0.tgz o2imsrepo
 196          helm repo update
 197          helm search repo firewall
 198
 199       Setup host net device over INF node
 200
 201       .. code:: bash
 202
 203          ssh sysadmin@<INF OAM IP>
 204          sudo ip link add name veth11 type veth peer name veth12
 205          sudo ip link add name veth21 type veth peer name veth22
 206          sudo ip link |grep veth
 207          exit
 208
 209    -  Create NfDeploymentDescriptor on the INF O2 DMS
 210
 211       .. code:: bash
 212
 213          curl --location --request POST "http://${OAM_IP}:30205/o2dms/v1/${dmsId}/O2dms_DeploymentLifecycle/NfDeploymentDescriptor" \
 214          --header 'Content-Type: application/json' \
 215          --data-raw '{
 216            "name": "cfwdesc1",
 217            "description": "demo nf deployment descriptor",
 218            "artifactRepoUrl": "http://'${NODE_IP}':30330",
 219            "artifactName": "firewall-host-netdevice",
 220            "inputParams":
 221            "{\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}",
 222            "outputParams": "{\"output1\": 100}"
 223          }'
 224
 225          curl --location --request GET "http://${OAM_IP}:30205/o2dms/v1/${dmsId}/O2dms_DeploymentLifecycle/NfDeploymentDescriptor"
 226
 227          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`
 228
 229          echo ${descId} # check the exported descriptor id
 230
 231    -  Create NfDeployment on the INF O2 DMS
 232
 233       When you have an descriptor of deployment, you can create a
 234       NfDeployment, it will trigger an event inside of the IMS/DMS, and
 235       use the K8S API to create a real pod of the firewall sample
 236
 237       .. code:: bash
 238
 239          curl --location --request POST "http://${OAM_IP}:30205/o2dms/v1/${dmsId}/O2dms_DeploymentLifecycle/NfDeployment" \
 240          --header 'Content-Type: application/json' \
 241          --data-raw '{
 242            "name": "cfw100",
 243            "description": "demo nf deployment",
 244            "descriptorId": "'${descId}'",
 245            "parentDeploymentId": ""
 246          }'
 247
 248          curl --location --request GET "http://${OAM_IP}:30205/o2dms/v1/${dmsId}/O2dms_DeploymentLifecycle/NfDeployment"
 249
 250    -  Check pods of the firewall sample
 251
 252       .. code:: bash
 253
 254          kubectl get pods
 255
 256    -  Delete the deployment we just created
 257
 258       .. code:: shell
 259
 260          export NfDeploymentId=`curl --location --request GET "http://${OAM_IP}:30205/o2dms/v1/${dmsId}/O2dms_DeploymentLifecycle/NfDeployment" 2>/dev/null | jq .[].id | xargs echo`
 261
 262          echo ${NfDeploymentId} # Check the exported deployment id
 263
 264          curl --location --request DELETE "http://${OAM_IP}:30205/o2dms/v1/${dmsId}/O2dms_DeploymentLifecycle/NfDeployment/${NfDeploymentId}"
 265
 266 -  Use Kubernetes Control Client through O2 DMS profile
 267
 268    Assume you have kubectl command tool installed on your Linux
 269    environment.
 270
 271    And install the ‘jq’ command for your Linux bash terminal. If you are
 272    use ubuntu, you can following below command to install it.
 273
 274    .. code:: bash
 275
 276       # install the 'jq' command
 277       sudo apt-get install -y jq
 278
 279       # install 'kubectl' command
 280       sudo apt-get install -y apt-transport-https
 281       echo "deb http://mirrors.ustc.edu.cn/kubernetes/apt kubernetes-xenial main" | \
 282       sudo tee -a /etc/apt/sources.list.d/kubernetes.list
 283       gpg --keyserver keyserver.ubuntu.com --recv-keys 836F4BEB
 284       gpg --export --armor 836F4BEB | sudo apt-key add -
 285       sudo apt-get update
 286       sudo apt-get install -y kubectl
 287
 288    We need to get Kubernetes profile to set up the kubectl command tool.
 289
 290    Get the DMS Id in the INF O2 service, and set it into bash
 291    environment.
 292
 293    .. code:: bash
 294
 295       # Get all DMS ID, and print them with command
 296       dmsIDs=$(curl -s -X 'GET' \
 297         "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/deploymentManagers" \
 298         -H 'accept: application/json' | jq --raw-output '.[]["deploymentManagerId"]')
 299       for i in $dmsIDs;do echo ${i};done;
 300
 301       # Choose one DMS and set it to bash environment, here I set the first one
 302       export dmsID=$(curl -s -X 'GET' \
 303         "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/deploymentManagers" \
 304         -H 'accept: application/json' | jq --raw-output '.[0]["deploymentManagerId"]')
 305
 306       echo ${dmsID} # check the exported DMS Id
 307
 308    The profile of the ‘kubectl’ need the cluster name, I assume it set
 309    to “o2dmsk8s1”.
 310
 311    It also need the server endpoint address, username and authority, and
 312    for the environment that has Certificate Authority validation, it
 313    needs the CA data to be set up.
 314
 315    .. code:: bash
 316
 317       CLUSTER_NAME="o2dmsk8s1" # set the cluster name
 318
 319       K8S_SERVER=$(curl -s -X 'GET' \
 320         "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/deploymentManagers/${dmsID}?profile=sol018" \
 321         -H 'accept: application/json' | jq --raw-output '.["profileData"]["cluster_api_endpoint"]')
 322       K8S_CA_DATA=$(curl -s -X 'GET' \
 323         "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/deploymentManagers/${dmsID}?profile=sol018" \
 324         -H 'accept: application/json' | jq --raw-output '.["profileData"]["cluster_ca_cert"]')
 325
 326       K8S_USER_NAME=$(curl -s -X 'GET' \
 327         "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/deploymentManagers/${dmsID}?profile=sol018" \
 328         -H 'accept: application/json' | jq --raw-output '.["profileData"]["admin_user"]')
 329       K8S_USER_CLIENT_CERT_DATA=$(curl -s -X 'GET' \
 330         "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/deploymentManagers/${dmsID}?profile=sol018" \
 331         -H 'accept: application/json' | jq --raw-output '.["profileData"]["admin_client_cert"]')
 332       K8S_USER_CLIENT_KEY_DATA=$(curl -s -X 'GET' \
 333         "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/deploymentManagers/${dmsID}?profile=sol018" \
 334         -H 'accept: application/json' | jq --raw-output '.["profileData"]["admin_client_key"]')
 335
 336
 337       # If you do not want to set up the CA data, you can execute following command without the secure checking
 338       # kubectl config set-cluster ${CLUSTER_NAME} --server=${K8S_SERVER} --insecure-skip-tls-verify
 339
 340       kubectl config set-cluster ${CLUSTER_NAME} --server=${K8S_SERVER}
 341       kubectl config set clusters.${CLUSTER_NAME}.certificate-authority-data ${K8S_CA_DATA}
 342
 343       kubectl config set-credentials ${K8S_USER_NAME}
 344       kubectl config set users.${K8S_USER_NAME}.client-certificate-data ${K8S_USER_CLIENT_CERT_DATA}
 345       kubectl config set users.${K8S_USER_NAME}.client-key-data ${K8S_USER_CLIENT_KEY_DATA}
 346
 347       # set the context and use it
 348       kubectl config set-context ${K8S_USER_NAME}@${CLUSTER_NAME} --cluster=${CLUSTER_NAME} --user ${K8S_USER_NAME}
 349       kubectl config use-context ${K8S_USER_NAME}@${CLUSTER_NAME}
 350
 351       kubectl get ns # check the command working with this context
 352
 353
 354    Now you can use “kubectl”, it means you set up successful of the
 355    Kubernetes client. But, it use the default admin user, so I recommend
 356    you create an account for yourself.
 357
 358    Create a new user and account for K8S with “cluster-admin” role. And,
 359    set the token of this user to the base environment.
 360
 361    .. code:: bash
 362
 363       USER="admin-user"
 364       NAMESPACE="kube-system"
 365
 366       cat <<EOF > admin-login.yaml
 367       apiVersion: v1
 368       kind: ServiceAccount
 369       metadata:
 370         name: ${USER}
 371         namespace: kube-system
 372       ---
 373       apiVersion: rbac.authorization.k8s.io/v1
 374       kind: ClusterRoleBinding
 375       metadata:
 376         name: ${USER}
 377       roleRef:
 378         apiGroup: rbac.authorization.k8s.io
 379         kind: ClusterRole
 380         name: cluster-admin
 381       subjects:
 382       - kind: ServiceAccount
 383         name: ${USER}
 384         namespace: kube-system
 385       EOF
 386
 387       kubectl apply -f admin-login.yaml
 388       TOKEN_DATA=$(kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep ${USER} | awk '{print $1}') | grep "token:" | awk '{print $2}')
 389       echo $TOKEN_DATA
 390
 391    Set the new user in ‘kubectl’ replace the original user, and set the
 392    default namespace into the context.
 393
 394    .. code:: bash
 395
 396       NAMESPACE=default
 397       TOKEN_DATA=<TOKEN_DATA from INF>
 398
 399       USER="admin-user"
 400       CLUSTER_NAME="o2dmsk8s1"
 401
 402       kubectl config set-credentials ${USER} --token=$TOKEN_DATA
 403       kubectl config set-context ${USER}@inf-cluster --cluster=${CLUSTER_NAME} --user ${USER} --namespace=${NAMESPACE}
 404       kubectl config use-context ${USER}@inf-cluster