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, and you
  12    have the token of the O2 service.
  13
  14    .. code:: bash
  15
  16       export OAM_IP=<INF_OAM_IP>
  17       export SMO_TOKEN_DATA=<TOKEN of O2 Service>
  18
  19 -  Discover INF platform inventory
  20
  21    -  INF platform auto-discovery
  22
  23       After you installed the INF O2 service, it will automatically
  24       discover the INF through the parameters that you give from the
  25       “*o2service-override.yaml*”
  26
  27       The below command can get the INF platform information as O-Cloud
  28
  29       .. code:: shell
  30
  31          curl -k -X 'GET' \
  32            "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/" \
  33            -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}"
  34
  35    -  Resource pool
  36
  37       The INF platform is a standalone environment, it has one resource
  38       pool. If the INF platform is a distributed cloud environment, the
  39       central cloud will be one resource pool, and each of the sub-cloud
  40       will be a resource pool. All the resources that belong to the
  41       cloud will be organized into the resource pool.
  42
  43       Get the resource pool information through this interface
  44
  45       .. code:: shell
  46
  47          curl -k -X 'GET' \
  48            "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/resourcePools" \
  49            -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}"
  50
  51          # export the first resource pool id
  52          export resourcePoolId=`curl -k -X 'GET' "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/resourcePools"   -H 'accept: application/json' -H "Authorization: Bearer $SMO_TOKEN_DATA" 2>/dev/null | jq .[0].resourcePoolId | xargs echo`
  53
  54          echo ${resourcePoolId} # check the exported resource pool id
  55
  56    -  Resource type
  57
  58       Resource type defined what type is the specified resource, like a
  59       physical machine, memory, or CPU
  60
  61       Show all resource type
  62
  63       .. code:: shell
  64
  65          curl -k -X 'GET' \
  66            "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/resourceTypes" \
  67            -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}"
  68
  69    -  Resource
  70
  71       Get the list of all resources, the value of *resourcePoolId* from
  72       the result of the resource pool interface
  73
  74       .. code:: shell
  75
  76          curl -k -X 'GET' \
  77          "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/resourcePools/${resourcePoolId}/resources" \
  78          -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}"
  79
  80       To get the detail of one resource, need to export one specific
  81       resource id that wants to check
  82
  83       .. code:: shell
  84
  85          # export the first resource id in the resource pool
  86          export resourceId=`curl -k -X 'GET' "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/resourcePools/${resourcePoolId}/resources"   -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}" 2>/dev/null | jq .[0].resourceId | xargs echo`
  87
  88          echo ${resourceId} # check the exported resource id
  89
  90          # Get the detail of one specific resource
  91          curl -k -X 'GET' \
  92          "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/resourcePools/${resourcePoolId}/resources/${resourceId}" \
  93          -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}"
  94
  95    -  Deployment manager services endpoint
  96
  97       The Deployment Manager Service (DMS) related to this IMS
  98       information you can use the below API to check
  99
 100       .. code:: shell
 101
 102          curl -k -X 'GET' \
 103            "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/deploymentManagers" \
 104            -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}"
 105
 106 -  Provisioning INF platform with SMO endpoint configuration
 107
 108    Assume you have an SMO, and prepare the configuration of the INF
 109    platform with the SMO endpoint address before the O2 service
 110    installation. This provisioning of the INF O2 service will make a
 111    request from the INF O2 service to SMO while the O2 service
 112    installing, which make SMO know the O2 service is working.
 113
 114    After you installed the INF O2 service, it will automatically
 115    register the SMO through the parameters that you give from the
 116    “*o2app.conf*”
 117
 118    .. code:: bash
 119
 120       export OCLOUD_GLOBAL_ID=<Ocloud global UUID defined by SMO>
 121       export SMO_REGISTER_URL=<SMO Register URL for O2 service>
 122
 123       cat <<EOF > o2app.conf
 124       [DEFAULT]
 125
 126       ocloud_global_id = ${OCLOUD_GLOBAL_ID}
 127       smo_register_url = ${SMO_REGISTER_URL}
 128       ...
 129
 130 -  Subscribe to the INF platform resource change notification
 131
 132    Assume you have an SMO, and the SMO has an API that can receive
 133    callback request
 134
 135    -  Create a subscription to the INF O2 IMS
 136
 137       .. code:: bash
 138
 139          export SMO_SUBSCRIBE_CALLBACK=<The Callback URL for SMO Subscribe resource>
 140          export SMO_CONSUMER_SUBSCRIPTION_ID=<The Subscription ID of the SMO Consumer>
 141
 142          curl -k -X 'POST' \
 143            "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/subscriptions" \
 144            -H 'accept: application/json' \
 145            -H 'Content-Type: application/json' \
 146            -H "Authorization: Bearer ${SMO_TOKEN_DATA}" \
 147            -d '{
 148            "callback": "'${SMO_SUBSCRIBE_CALLBACK}'",
 149            "consumerSubscriptionId": "'${SMO_CONSUMER_SUBSCRIPTION_ID}'",
 150            "filter": ""
 151          }'
 152
 153    -  Handle resource change notification
 154
 155       When the SMO callback API gets the notification that the resource
 156       of INF platform changing, use the URL to get the latest resource
 157       information to update its database
 158
 159 -  Subscribe to the INF platform alarm change notification
 160
 161    Assume you have an SMO, and the SMO has an API that can receive
 162    callback request
 163
 164    -  Create an alarm subscription to the INF O2 IMS
 165
 166       .. code:: bash
 167
 168          export SMO_SUBSCRIBE_CALLBACK=<The Callback URL for SMO Subscribe alarm>
 169          export SMO_CONSUMER_SUBSCRIPTION_ID=<The Subscription ID of the SMO Consumer>
 170
 171          curl -k -X 'POST' \
 172            "https://${OAM_IP}:30205/o2ims-infrastructureMonitoring/v1/alarmSubscriptions" \
 173            -H 'accept: application/json' \
 174            -H 'Content-Type: application/json' \
 175            -H "Authorization: Bearer ${SMO_TOKEN_DATA}" \
 176            -d '{
 177            "callback": "'${SMO_SUBSCRIBE_CALLBACK}'",
 178            "consumerSubscriptionId": "'${SMO_CONSUMER_SUBSCRIPTION_ID}'",
 179            "filter": ""
 180          }'
 181
 182    -  Handle alarm change notification
 183
 184       When the SMO callback API gets the alarm of the INF platform, use
 185       the URL to get the latest alarm event record information to get
 186       more details
 187
 188 -  Use Kubernetes Control Client through O2 DMS profile
 189
 190    Assume you have the kubectl command tool on your local Linux
 191    environment.
 192
 193    And install the ‘jq’ command for your Linux bash terminal. If you are
 194    using Ubuntu, you can follow the below command to install it.
 195
 196    .. code:: bash
 197
 198       # install the 'jq' command
 199       sudo apt-get install -y jq
 200
 201       # install 'kubectl' command
 202       sudo apt-get install -y apt-transport-https
 203       echo "deb http://mirrors.ustc.edu.cn/kubernetes/apt kubernetes-xenial main" | \
 204       sudo tee -a /etc/apt/sources.list.d/kubernetes.list
 205       gpg --keyserver keyserver.ubuntu.com --recv-keys 836F4BEB
 206       gpg --export --armor 836F4BEB | sudo apt-key add -
 207       sudo apt-get update
 208       sudo apt-get install -y kubectl
 209
 210    We need to get the Kubernetes profile to set up the kubectl command
 211    tool.
 212
 213    Get the DMS Id in the INF O2 service, and set it into bash
 214    environment.
 215
 216    .. code:: bash
 217
 218       # Get all DMS ID, and print them with command
 219       dmsIDs=$(curl -k -s -X 'GET' \
 220       "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/deploymentManagers" \
 221       -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}" \
 222       | jq --raw-output '.[]["deploymentManagerId"]')
 223       for i in $dmsIDs;do echo ${i};done;
 224
 225       # Choose one DMS and set it to bash environment, here I set the first one
 226       export dmsID=$(curl -k -s -X 'GET' \
 227         "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/deploymentManagers" \
 228         -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}" \
 229         | jq --raw-output '.[0]["deploymentManagerId"]')
 230
 231       echo ${dmsID} # check the exported DMS Id
 232
 233    The profile of the ‘kubectl’ need the cluster name, I assume it is
 234    set to “o2dmsk8s1”.
 235
 236    It also needs the server endpoint address, username, and authority,
 237    and for the environment that has Certificate Authority validation, it
 238    needs the CA data to be set up.
 239
 240    .. code:: bash
 241
 242       CLUSTER_NAME="o2dmsk8s1" # set the cluster name
 243
 244       K8S_SERVER=$(curl -k -s -X 'GET' \
 245         "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/deploymentManagers/${dmsID}?profile=native_k8sapi" \
 246         -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}" \
 247         | jq --raw-output '.["extensions"]["profileData"]["cluster_api_endpoint"]')
 248       K8S_CA_DATA=$(curl -k -s -X 'GET' \
 249         "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/deploymentManagers/${dmsID}?profile=native_k8sapi" \
 250         -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}" \
 251         | jq --raw-output '.["extensions"]["profileData"]["cluster_ca_cert"]')
 252
 253       K8S_USER_NAME=$(curl -k -s -X 'GET' \
 254         "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/deploymentManagers/${dmsID}?profile=native_k8sapi" \
 255         -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}" \
 256         | jq --raw-output '.["extensions"]["profileData"]["admin_user"]')
 257       K8S_USER_CLIENT_CERT_DATA=$(curl -k -s -X 'GET' \
 258         "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/deploymentManagers/${dmsID}?profile=native_k8sapi" \
 259         -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}" \
 260         | jq --raw-output '.["extensions"]["profileData"]["admin_client_cert"]')
 261       K8S_USER_CLIENT_KEY_DATA=$(curl -k -s -X 'GET' \
 262         "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/deploymentManagers/${dmsID}?profile=native_k8sapi" \
 263         -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}" \
 264         | jq --raw-output '.["extensions"]["profileData"]["admin_client_key"]')
 265
 266       # If you do not want to set up the CA data, you can execute following command without the secure checking
 267       # kubectl config set-cluster ${CLUSTER_NAME} --server=${K8S_SERVER} --insecure-skip-tls-verify
 268
 269       kubectl config set-cluster ${CLUSTER_NAME} --server=${K8S_SERVER}
 270       kubectl config set clusters.${CLUSTER_NAME}.certificate-authority-data ${K8S_CA_DATA}
 271
 272       kubectl config set-credentials ${K8S_USER_NAME}
 273       kubectl config set users.${K8S_USER_NAME}.client-certificate-data ${K8S_USER_CLIENT_CERT_DATA}
 274       kubectl config set users.${K8S_USER_NAME}.client-key-data ${K8S_USER_CLIENT_KEY_DATA}
 275
 276       # set the context and use it
 277       kubectl config set-context ${K8S_USER_NAME}@${CLUSTER_NAME} --cluster=${CLUSTER_NAME} --user ${K8S_USER_NAME}
 278       kubectl config use-context ${K8S_USER_NAME}@${CLUSTER_NAME}
 279
 280       kubectl get ns # check the command working with this context
 281
 282    Now you can use “kubectl”, which means you set up a successfully
 283    Kubernetes client. But, it uses the default admin user, so I
 284    recommend you create an account for yourself.
 285
 286    Create a new user and account for K8S with a “cluster-admin” role.
 287    And, set the token of this user to the base environment.
 288
 289    .. code:: bash
 290
 291       USER="admin-user"
 292       NAMESPACE="kube-system"
 293
 294       cat <<EOF > admin-login.yaml
 295       apiVersion: v1
 296       kind: ServiceAccount
 297       metadata:
 298         name: ${USER}
 299         namespace: kube-system
 300       ---
 301       apiVersion: rbac.authorization.k8s.io/v1
 302       kind: ClusterRoleBinding
 303       metadata:
 304         name: ${USER}
 305       roleRef:
 306         apiGroup: rbac.authorization.k8s.io
 307         kind: ClusterRole
 308         name: cluster-admin
 309       subjects:
 310       - kind: ServiceAccount
 311         name: ${USER}
 312         namespace: kube-system
 313       EOF
 314
 315       kubectl apply -f admin-login.yaml
 316       TOKEN_DATA=$(kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep ${USER} | awk '{print $1}') | grep "token:" | awk '{print $2}')
 317       echo $TOKEN_DATA
 318
 319    Set the new user in ‘kubectl’ replace the original user, and set the
 320    default namespace into the context.
 321
 322    .. code:: bash
 323
 324       NAMESPACE=default
 325       TOKEN_DATA=<TOKEN_DATA from INF>
 326
 327       USER="admin-user"
 328       CLUSTER_NAME="o2dmsk8s1"
 329
 330       kubectl config set-credentials ${USER} --token=$TOKEN_DATA
 331       kubectl config set-context ${USER}@inf-cluster --cluster=${CLUSTER_NAME} --user ${USER} --namespace=${NAMESPACE}
 332       kubectl config use-context ${USER}@inf-cluster