Merge "OAuth2 support"
[pti/o2.git] / 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