From 5795d999023312c80e2bfd7218275cf485a0173e Mon Sep 17 00:00:00 2001 From: "Zhang Rong(Jon)" Date: Fri, 16 Dec 2022 17:28:34 +0800 Subject: [PATCH] Fix api.rst missing; Update the API name in the swagger; Update user guide Issue-ID: INF-387 Signed-off-by: Zhang Rong(Jon) Change-Id: I8c560305b67232dfaac4fd47509bb3076b8a76c6 --- docs/api-docs.rst | 5 +- docs/api.rst | 12 ++ docs/conf.py | 3 +- docs/index.rst | 1 + docs/swagger.json | 102 +++++++------- docs/swagger.yaml | 48 +++---- docs/user-guide.rst | 334 +++++++++++++++++--------------------------- o2ims/views/alarm_route.py | 12 +- o2ims/views/api_ns.py | 2 + o2ims/views/ocloud_route.py | 22 +-- 10 files changed, 246 insertions(+), 295 deletions(-) create mode 100644 docs/api.rst diff --git a/docs/api-docs.rst b/docs/api-docs.rst index e2971dc..1419fa7 100755 --- a/docs/api-docs.rst +++ b/docs/api-docs.rst @@ -11,7 +11,6 @@ :width: 40px -========================== O-RAN O2 API Definition v1 ========================== @@ -24,8 +23,8 @@ The typical port used for the O-RAN O2 REST API is 30205. Here we describe the API to access the O2 API. -O-RAN O2 API v1 -=============== +O2 API v1 +--------- The O2 API v1 provides API includes O2ims_InfrastructureInventory, O2ims_InfrastructureMonitoring and Kubernetes native API based O2dms interfaces. diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..2867d76 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,12 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2021-2022 Wind River Systems, Inc. + + +INF O2 Services API +=================== + +This page is deprecated, please go to the `O-RAN O2 API Definition v1`_. + + +.. _`O-RAN O2 API Definition v1`: ./api-docs.html diff --git a/docs/conf.py b/docs/conf.py index 93ba0c4..68338b2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -17,7 +17,8 @@ linkcheck_ignore = [ 'http://localhost.*', 'http://127.0.0.1.*', 'https://gerrit.o-ran-sc.org.*', - './oran-o2-api.html' # Generated file that doesn't exist at link check. + './oran-o2-api.html', # Generated file that doesn't exist at link check. + './api-docs.html' ] extensions = ['sphinxcontrib.redoc', 'sphinx.ext.intersphinx'] diff --git a/docs/index.rst b/docs/index.rst index 41f031b..47b9146 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,5 +17,6 @@ Welcome to INF O2 documentation installation-guide.rst user-guide.rst api-docs.rst + api.rst * :ref:`search` diff --git a/docs/swagger.json b/docs/swagger.json index bbdefbb..b00c4e4 100644 --- a/docs/swagger.json +++ b/docs/swagger.json @@ -9,7 +9,7 @@ "description": "Success" } }, - "operationId": "get_inventory_version", + "operationId": "Get Inventory Version", "tags": [ "O2IMS_Inventory" ] @@ -54,7 +54,7 @@ } } }, - "operationId": "get_oclouds_list_router", + "operationId": "Get Ocloud Information", "tags": [ "O2IMS_Inventory" ] @@ -99,7 +99,7 @@ } } }, - "operationId": "get_oclouds_list_router", + "operationId": "Get Ocloud Information", "tags": [ "O2IMS_Inventory" ] @@ -112,7 +112,7 @@ "description": "Success" } }, - "operationId": "get_version_router", + "operationId": "Get Inventory API version", "tags": [ "O2IMS_Inventory" ] @@ -170,7 +170,7 @@ } } }, - "operationId": "get_deployment_managers_list_router", + "operationId": "Get Deployment Manager List", "tags": [ "O2IMS_Inventory" ] @@ -228,7 +228,7 @@ } } }, - "operationId": "Get deployment manager", + "operationId": "Get Deployment Manager Information", "tags": [ "O2IMS_Inventory" ] @@ -286,7 +286,7 @@ } } }, - "operationId": "get_resource_pools_list_router", + "operationId": "Get Resource Pool List", "tags": [ "O2IMS_Inventory" ] @@ -338,7 +338,7 @@ } } }, - "operationId": "Get resource pool", + "operationId": "Get Resource Pool Information", "tags": [ "O2IMS_Inventory" ] @@ -406,7 +406,7 @@ } } }, - "operationId": "get_resources_list_router", + "operationId": "Get Resource List", "tags": [ "O2IMS_Inventory" ] @@ -465,7 +465,7 @@ } } }, - "operationId": "Get resource", + "operationId": "Get Resource Information", "tags": [ "O2IMS_Inventory" ] @@ -523,7 +523,7 @@ } } }, - "operationId": "get_resource_types_list_router", + "operationId": "Get Resource Type List", "tags": [ "O2IMS_Inventory" ] @@ -575,7 +575,7 @@ } } }, - "operationId": "Get resource type", + "operationId": "Get Resource Type Information", "tags": [ "O2IMS_Inventory" ] @@ -594,7 +594,7 @@ } } }, - "operationId": "List subscriptions", + "operationId": "Get Subscription List", "parameters": [ { "in": "query", @@ -647,7 +647,7 @@ } } }, - "operationId": "Create a subscription", + "operationId": "Create a Subscription", "parameters": [ { "name": "payload", @@ -673,6 +673,20 @@ "type": "string" } ], + "delete": { + "responses": { + "404": { + "description": "Subscription not found" + }, + "200": { + "description": "Subscription deleted" + } + }, + "operationId": "Delete a Subscription", + "tags": [ + "O2IMS_Inventory" + ] + }, "get": { "responses": { "404": { @@ -685,7 +699,7 @@ } } }, - "operationId": "Get subscription by ID", + "operationId": "Get Subscription Information", "parameters": [ { "in": "query", @@ -715,20 +729,6 @@ "tags": [ "O2IMS_Inventory" ] - }, - "delete": { - "responses": { - "404": { - "description": "Subscription not found" - }, - "200": { - "description": "Subscription deleted" - } - }, - "operationId": "Delete subscription by ID", - "tags": [ - "O2IMS_Inventory" - ] } }, "/o2ims-infrastructureMonitoring/api_versions": { @@ -738,7 +738,7 @@ "description": "Success" } }, - "operationId": "get_monitoring_version", + "operationId": "Get Monitoring Version", "tags": [ "O2IMS_InfrastructureMonitoring" ] @@ -757,7 +757,7 @@ } } }, - "operationId": "List alarm subscriptions", + "operationId": "Get Alarm Subscription List", "parameters": [ { "in": "query", @@ -810,7 +810,7 @@ } } }, - "operationId": "Create a alarm subscription", + "operationId": "Create a Alarm Subscription", "parameters": [ { "name": "payload", @@ -836,6 +836,20 @@ "type": "string" } ], + "delete": { + "responses": { + "404": { + "description": "Alarm Subscription not found" + }, + "200": { + "description": "Subscription deleted" + } + }, + "operationId": "Delete an Alarm Subscription", + "tags": [ + "O2IMS_InfrastructureMonitoring" + ] + }, "get": { "responses": { "404": { @@ -848,7 +862,7 @@ } } }, - "operationId": "Get Alarm Subscription by ID", + "operationId": "Get Alarm Subscription Information", "parameters": [ { "in": "query", @@ -878,20 +892,6 @@ "tags": [ "O2IMS_InfrastructureMonitoring" ] - }, - "delete": { - "responses": { - "404": { - "description": "Alarm Subscription not found" - }, - "200": { - "description": "Subscription deleted" - } - }, - "operationId": "Delete subscription by ID", - "tags": [ - "O2IMS_InfrastructureMonitoring" - ] } }, "/o2ims-infrastructureMonitoring/v1/alarms": { @@ -946,7 +946,7 @@ } } }, - "operationId": "get_alarm_list_router", + "operationId": "Get Alarm Event Record List", "tags": [ "O2IMS_InfrastructureMonitoring" ] @@ -998,7 +998,7 @@ } } }, - "operationId": "Get AlarmEventRecord", + "operationId": "Get Alarm Event Record Information", "tags": [ "O2IMS_InfrastructureMonitoring" ] @@ -1011,7 +1011,7 @@ "description": "Success" } }, - "operationId": "get_version_router", + "operationId": "Get Monitoring API version", "tags": [ "O2IMS_InfrastructureMonitoring" ] @@ -1608,4 +1608,4 @@ "description": "Return a custom message and 500 status code" } } -} \ No newline at end of file +} diff --git a/docs/swagger.yaml b/docs/swagger.yaml index fa0e624..278fb91 100755 --- a/docs/swagger.yaml +++ b/docs/swagger.yaml @@ -19,7 +19,7 @@ paths: get: tags: - O2IMS_Inventory - operationId: get_inventory_version + operationId: Get Inventory Version parameters: [] responses: "200": @@ -28,7 +28,7 @@ paths: get: tags: - O2IMS_Inventory - operationId: get_oclouds_list_router + operationId: Get Ocloud Information parameters: - name: exclude_default in: query @@ -61,7 +61,7 @@ paths: get: tags: - O2IMS_Inventory - operationId: get_oclouds_list_router + operationId: Get Ocloud Information parameters: - name: exclude_default in: query @@ -94,7 +94,7 @@ paths: get: tags: - O2IMS_Inventory - operationId: get_version_router + operationId: Get Inventory API version parameters: [] responses: "200": @@ -103,7 +103,7 @@ paths: get: tags: - O2IMS_Inventory - operationId: get_deployment_managers_list_router + operationId: Get Deployment Manager List parameters: - name: filter in: query @@ -147,7 +147,7 @@ paths: get: tags: - O2IMS_Inventory - operationId: Get deployment manager + operationId: Get Deployment Manager Information parameters: - name: exclude_default in: query @@ -190,7 +190,7 @@ paths: get: tags: - O2IMS_Inventory - operationId: get_resource_pools_list_router + operationId: Get Resource Pool List parameters: - name: filter in: query @@ -234,7 +234,7 @@ paths: get: tags: - O2IMS_Inventory - operationId: Get resource pool + operationId: Get Resource Pool Information parameters: - name: exclude_default in: query @@ -272,7 +272,7 @@ paths: get: tags: - O2IMS_Inventory - operationId: get_resources_list_router + operationId: Get Resource List parameters: - name: filter in: query @@ -323,7 +323,7 @@ paths: get: tags: - O2IMS_Inventory - operationId: Get resource + operationId: Get Resource Information parameters: - name: exclude_default in: query @@ -366,7 +366,7 @@ paths: get: tags: - O2IMS_Inventory - operationId: get_resource_types_list_router + operationId: Get Resource Type List parameters: - name: filter in: query @@ -410,7 +410,7 @@ paths: get: tags: - O2IMS_Inventory - operationId: Get resource type + operationId: Get Resource Type Information parameters: - name: exclude_default in: query @@ -448,7 +448,7 @@ paths: get: tags: - O2IMS_Inventory - operationId: List subscriptions + operationId: Get Subscription List parameters: - name: filter in: query @@ -491,7 +491,7 @@ paths: post: tags: - O2IMS_Inventory - operationId: Create a subscription + operationId: Create a Subscription parameters: - in: body name: payload @@ -507,7 +507,7 @@ paths: get: tags: - O2IMS_Inventory - operationId: Get subscription by ID + operationId: Get Subscription Information parameters: - name: subscriptionID in: path @@ -544,7 +544,7 @@ paths: delete: tags: - O2IMS_Inventory - operationId: Delete subscription by ID + operationId: Delete a Subscription parameters: - name: subscriptionID in: path @@ -560,7 +560,7 @@ paths: get: tags: - O2IMS_InfrastructureMonitoring - operationId: get_monitoring_version + operationId: Get Monitoring Version parameters: [] responses: "200": @@ -569,7 +569,7 @@ paths: get: tags: - O2IMS_InfrastructureMonitoring - operationId: List alarm subscriptions + operationId: Get Alarm Subscription List parameters: - name: filter in: query @@ -612,7 +612,7 @@ paths: post: tags: - O2IMS_InfrastructureMonitoring - operationId: Create a alarm subscription + operationId: Create a Alarm Subscription parameters: - in: body name: payload @@ -628,7 +628,7 @@ paths: get: tags: - O2IMS_InfrastructureMonitoring - operationId: Get Alarm Subscription by ID + operationId: Get Alarm Subscription Information parameters: - name: alarmSubscriptionID in: path @@ -665,7 +665,7 @@ paths: delete: tags: - O2IMS_InfrastructureMonitoring - operationId: Delete subscription by ID + operationId: Delete an Alarm Subscription parameters: - name: alarmSubscriptionID in: path @@ -681,7 +681,7 @@ paths: get: tags: - O2IMS_InfrastructureMonitoring - operationId: get_alarm_list_router + operationId: Get Alarm Event Record List parameters: - name: filter in: query @@ -725,7 +725,7 @@ paths: get: tags: - O2IMS_InfrastructureMonitoring - operationId: Get AlarmEventRecord + operationId: Get Alarm Event Record Information parameters: - name: exclude_default in: query @@ -763,7 +763,7 @@ paths: get: tags: - O2IMS_InfrastructureMonitoring - operationId: get_version_router + operationId: Get Monitoring API version parameters: [] responses: "200": diff --git a/docs/user-guide.rst b/docs/user-guide.rst index 5d64874..5b173c9 100644 --- a/docs/user-guide.rst +++ b/docs/user-guide.rst @@ -8,44 +8,48 @@ INF O2 Service User Guide This guide will introduce the process that make INF O2 interface work with SMO. -- Assume you have an O2 service with INF platform environment +- Assume you have an O2 service with INF platform environment, and you + have the token of the O2 service. .. code:: bash export OAM_IP= + export SMO_TOKEN_DATA= - Discover INF platform inventory - - INF platform auto discovery + - INF platform auto-discovery After you installed the INF O2 service, it will automatically discover the INF through the parameters that you give from the “*o2service-override.yaml*” - Below command can get the INF platform information as O-Cloud + The below command can get the INF platform information as O-Cloud .. code:: shell - curl -X 'GET' \ - "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/" \ - -H 'accept: application/json' + curl -k -X 'GET' \ + "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/" \ + -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}" - Resource pool - One INF platform have one resource pool, all the resources that - belong to this INF platform will be organized into this resource - pool + The INF platform is a standalone environment, it has one resource + pool. If the INF platform is a distributed cloud environment, the + central cloud will be one resource pool, and each of the sub-cloud + will be a resource pool. All the resources that belong to the + cloud will be organized into the resource pool. Get the resource pool information through this interface .. code:: shell - curl -X 'GET' \ - "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/resourcePools" \ - -H 'accept: application/json' + curl -k -X 'GET' \ + "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/resourcePools" \ + -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}" - # export resource pool id - 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` + # export the first resource pool id + 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` echo ${resourcePoolId} # check the exported resource pool id @@ -58,218 +62,136 @@ with SMO. .. code:: shell - curl -X 'GET' \ - "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/resourceTypes" \ - -H 'accept: application/json' + curl -k -X 'GET' \ + "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/resourceTypes" \ + -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}" - Resource Get the list of all resources, the value of *resourcePoolId* from - the result of resource pool interface + the result of the resource pool interface .. code:: shell - curl -X 'GET' \ - "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/resourcePools/${resourcePoolId}/resources" \ - -H 'accept: application/json' + curl -k -X 'GET' \ + "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/resourcePools/${resourcePoolId}/resources" \ + -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}" - Get detail of one resource, need to export one specific resource - id that wants to check + To get the detail of one resource, need to export one specific + resource id that wants to check .. code:: shell - curl -X 'GET' \ - "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/resourcePools/${resourcePoolId}/resources/${resourceId}" \ - -H 'accept: application/json' + # export the first resource id in the resource pool + 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` + + echo ${resourceId} # check the exported resource id + + # Get the detail of one specific resource + curl -k -X 'GET' \ + "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/resourcePools/${resourcePoolId}/resources/${resourceId}" \ + -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}" - Deployment manager services endpoint - The Deployment Manager Service (DMS) that related to this IMS - information you can use below API to check + The Deployment Manager Service (DMS) related to this IMS + information you can use the below API to check .. code:: shell - curl -X 'GET' \ - "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/deploymentManagers" \ - -H 'accept: application/json' + curl -k -X 'GET' \ + "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/deploymentManagers" \ + -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}" - Provisioning INF platform with SMO endpoint configuration - Assume you have an SMO, then configure INF platform with SMO endpoint - address. This provisioning of INF O2 service will make a request from - INF O2 service to SMO, that make SMO know the O2 service is working. + Assume you have an SMO, and prepare the configuration of the INF + platform with the SMO endpoint address before the O2 service + installation. This provisioning of the INF O2 service will make a + request from the INF O2 service to SMO while the O2 service + installing, which make SMO know the O2 service is working. - It needs SMO to have an API like - “*http(s)://SMO_HOST:SMO_PORT/registration*”, which can accept JSON - format data. + After you installed the INF O2 service, it will automatically + register the SMO through the parameters that you give from the + “*o2app.conf*” .. code:: bash - curl -X 'POST' \ - 'http://'${OAM_IP}':30205/provision/v1/smo-endpoint' \ - -H 'accept: application/json' \ - -H 'Content-Type: application/json' \ - -d '{ - "endpoint": "http://:/registration" - }' + export OCLOUD_GLOBAL_ID= + export SMO_REGISTER_URL= + + cat < o2app.conf + [DEFAULT] + + ocloud_global_id = ${OCLOUD_GLOBAL_ID} + smo_register_url = ${SMO_REGISTER_URL} + ... - Subscribe to the INF platform resource change notification - Assume you have an SMO, and the SMO have an API can be receive + Assume you have an SMO, and the SMO has an API that can receive callback request - - Create subscription in the INF O2 IMS + - Create a subscription to the INF O2 IMS .. code:: bash - curl -X 'POST' \ - "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/subscriptions" \ + export SMO_SUBSCRIBE_CALLBACK= + export SMO_CONSUMER_SUBSCRIPTION_ID= + + curl -k -X 'POST' \ + "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/subscriptions" \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ + -H "Authorization: Bearer ${SMO_TOKEN_DATA}" \ -d '{ - "callback": "http://SMO/address/to/callback", - "consumerSubscriptionId": "", - "filter": "" + "callback": "'${SMO_SUBSCRIBE_CALLBACK}'", + "consumerSubscriptionId": "'${SMO_CONSUMER_SUBSCRIPTION_ID}'", + "filter": "" }' - Handle resource change notification - When the SMO callback API get the notification that the resource + When the SMO callback API gets the notification that the resource of INF platform changing, use the URL to get the latest resource information to update its database -- Orchestrate CNF in helm chart - - On this sample, we prepare a firewall chart to test the - orchestration. - - We need to do some preparation to make the helm repo work and include - our firewall chart inside of the repository. - - Get the DMS Id in the INF O2 service, and set it into bash - environment - - .. code:: bash - - curl --location --request GET "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/deploymentManagers" - - export dmsId=`curl --location --request GET "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/deploymentManagers" 2>/dev/null | jq .[].deploymentManagerId | xargs echo` - - echo ${dmsId} # check the exported DMS id +- Subscribe to the INF platform alarm change notification - Using helm to deploy a chartmuseum to the INF platform - - .. code:: bash - - helm repo add chartmuseum https://chartmuseum.github.io/charts - helm repo update - helm pull chartmuseum/chartmuseum # download chartmuseum-3.4.0.tgz to local - tar zxvf chartmuseum-3.4.0.tgz - cat <chartmuseum-override.yaml - env: - open: - DISABLE_API: false - service: - type: NodePort - nodePort: 30330 - EOF - - helm install chartmuseumrepo chartmuseum/chartmuseum -f chartmuseum-override.yaml - kubectl get pods - Kubectl get services - - Update the helm repo and add the chartmusem into the repository - - .. code:: bash - - helm repo add o2imsrepo http://${NODE_IP}:30330 - helm repo update - - Download the firewall chart and push it into the repository - - .. code:: bash - - git clone https://github.com/biny993/firewall-host-netdevice.git - tar -zcvf firewall-host-netdevice-1.0.0.tgz firewall-host-netdevice/ - helm plugin install https://github.com/chartmuseum/helm-push.git - helm cm-push firewall-host-netdevice-1.0.0.tgz o2imsrepo - helm repo update - helm search repo firewall - - Setup host net device over INF node - - .. code:: bash - - ssh sysadmin@ - sudo ip link add name veth11 type veth peer name veth12 - sudo ip link add name veth21 type veth peer name veth22 - sudo ip link |grep veth - exit + Assume you have an SMO, and the SMO has an API that can receive + callback request - - Create NfDeploymentDescriptor on the INF O2 DMS + - Create an alarm subscription to the INF O2 IMS .. code:: bash - curl --location --request POST "http://${OAM_IP}:30205/o2dms/v1/${dmsId}/O2dms_DeploymentLifecycle/NfDeploymentDescriptor" \ - --header 'Content-Type: application/json' \ - --data-raw '{ - "name": "cfwdesc1", - "description": "demo nf deployment descriptor", - "artifactRepoUrl": "http://'${NODE_IP}':30330", - "artifactName": "firewall-host-netdevice", - "inputParams": - "{\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}", - "outputParams": "{\"output1\": 100}" - }' - - curl --location --request GET "http://${OAM_IP}:30205/o2dms/v1/${dmsId}/O2dms_DeploymentLifecycle/NfDeploymentDescriptor" - - 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` - - echo ${descId} # check the exported descriptor id - - - Create NfDeployment on the INF O2 DMS + export SMO_SUBSCRIBE_CALLBACK= + export SMO_CONSUMER_SUBSCRIPTION_ID= - When you have an descriptor of deployment, you can create a - NfDeployment, it will trigger an event inside of the IMS/DMS, and - use the K8S API to create a real pod of the firewall sample - - .. code:: bash - - curl --location --request POST "http://${OAM_IP}:30205/o2dms/v1/${dmsId}/O2dms_DeploymentLifecycle/NfDeployment" \ - --header 'Content-Type: application/json' \ - --data-raw '{ - "name": "cfw100", - "description": "demo nf deployment", - "descriptorId": "'${descId}'", - "parentDeploymentId": "" + curl -k -X 'POST' \ + "https://${OAM_IP}:30205/o2ims-infrastructureMonitoring/v1/alarmSubscriptions" \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer ${SMO_TOKEN_DATA}" \ + -d '{ + "callback": "'${SMO_SUBSCRIBE_CALLBACK}'", + "consumerSubscriptionId": "'${SMO_CONSUMER_SUBSCRIPTION_ID}'", + "filter": "" }' - curl --location --request GET "http://${OAM_IP}:30205/o2dms/v1/${dmsId}/O2dms_DeploymentLifecycle/NfDeployment" + - Handle alarm change notification - - Check pods of the firewall sample - - .. code:: bash - - kubectl get pods - - - Delete the deployment we just created - - .. code:: shell - - export NfDeploymentId=`curl --location --request GET "http://${OAM_IP}:30205/o2dms/v1/${dmsId}/O2dms_DeploymentLifecycle/NfDeployment" 2>/dev/null | jq .[].id | xargs echo` - - echo ${NfDeploymentId} # Check the exported deployment id - - curl --location --request DELETE "http://${OAM_IP}:30205/o2dms/v1/${dmsId}/O2dms_DeploymentLifecycle/NfDeployment/${NfDeploymentId}" + When the SMO callback API gets the alarm of the INF platform, use + the URL to get the latest alarm event record information to get + more details - Use Kubernetes Control Client through O2 DMS profile - Assume you have kubectl command tool installed on your Linux + Assume you have the kubectl command tool on your local Linux environment. And install the ‘jq’ command for your Linux bash terminal. If you are - use ubuntu, you can following below command to install it. + using Ubuntu, you can follow the below command to install it. .. code:: bash @@ -285,7 +207,8 @@ with SMO. sudo apt-get update sudo apt-get install -y kubectl - We need to get Kubernetes profile to set up the kubectl command tool. + We need to get the Kubernetes profile to set up the kubectl command + tool. Get the DMS Id in the INF O2 service, and set it into bash environment. @@ -293,46 +216,52 @@ with SMO. .. code:: bash # Get all DMS ID, and print them with command - dmsIDs=$(curl -s -X 'GET' \ - "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/deploymentManagers" \ - -H 'accept: application/json' | jq --raw-output '.[]["deploymentManagerId"]') + dmsIDs=$(curl -k -s -X 'GET' \ + "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/deploymentManagers" \ + -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}" \ + | jq --raw-output '.[]["deploymentManagerId"]') for i in $dmsIDs;do echo ${i};done; # Choose one DMS and set it to bash environment, here I set the first one - export dmsID=$(curl -s -X 'GET' \ - "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/deploymentManagers" \ - -H 'accept: application/json' | jq --raw-output '.[0]["deploymentManagerId"]') + export dmsID=$(curl -k -s -X 'GET' \ + "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/deploymentManagers" \ + -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}" \ + | jq --raw-output '.[0]["deploymentManagerId"]') echo ${dmsID} # check the exported DMS Id - The profile of the ‘kubectl’ need the cluster name, I assume it set - to “o2dmsk8s1”. + The profile of the ‘kubectl’ need the cluster name, I assume it is + set to “o2dmsk8s1”. - It also need the server endpoint address, username and authority, and - for the environment that has Certificate Authority validation, it + It also needs the server endpoint address, username, and authority, + and for the environment that has Certificate Authority validation, it needs the CA data to be set up. .. code:: bash CLUSTER_NAME="o2dmsk8s1" # set the cluster name - K8S_SERVER=$(curl -s -X 'GET' \ - "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/deploymentManagers/${dmsID}?profile=sol018" \ - -H 'accept: application/json' | jq --raw-output '.["profileData"]["cluster_api_endpoint"]') - K8S_CA_DATA=$(curl -s -X 'GET' \ - "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/deploymentManagers/${dmsID}?profile=sol018" \ - -H 'accept: application/json' | jq --raw-output '.["profileData"]["cluster_ca_cert"]') - - K8S_USER_NAME=$(curl -s -X 'GET' \ - "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/deploymentManagers/${dmsID}?profile=sol018" \ - -H 'accept: application/json' | jq --raw-output '.["profileData"]["admin_user"]') - K8S_USER_CLIENT_CERT_DATA=$(curl -s -X 'GET' \ - "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/deploymentManagers/${dmsID}?profile=sol018" \ - -H 'accept: application/json' | jq --raw-output '.["profileData"]["admin_client_cert"]') - K8S_USER_CLIENT_KEY_DATA=$(curl -s -X 'GET' \ - "http://${OAM_IP}:30205/o2ims_infrastructureInventory/v1/deploymentManagers/${dmsID}?profile=sol018" \ - -H 'accept: application/json' | jq --raw-output '.["profileData"]["admin_client_key"]') - + K8S_SERVER=$(curl -k -s -X 'GET' \ + "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/deploymentManagers/${dmsID}?profile=native_k8sapi" \ + -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}" \ + | jq --raw-output '.["extensions"]["profileData"]["cluster_api_endpoint"]') + K8S_CA_DATA=$(curl -k -s -X 'GET' \ + "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/deploymentManagers/${dmsID}?profile=native_k8sapi" \ + -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}" \ + | jq --raw-output '.["extensions"]["profileData"]["cluster_ca_cert"]') + + K8S_USER_NAME=$(curl -k -s -X 'GET' \ + "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/deploymentManagers/${dmsID}?profile=native_k8sapi" \ + -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}" \ + | jq --raw-output '.["extensions"]["profileData"]["admin_user"]') + K8S_USER_CLIENT_CERT_DATA=$(curl -k -s -X 'GET' \ + "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/deploymentManagers/${dmsID}?profile=native_k8sapi" \ + -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}" \ + | jq --raw-output '.["extensions"]["profileData"]["admin_client_cert"]') + K8S_USER_CLIENT_KEY_DATA=$(curl -k -s -X 'GET' \ + "https://${OAM_IP}:30205/o2ims-infrastructureInventory/v1/deploymentManagers/${dmsID}?profile=native_k8sapi" \ + -H 'accept: application/json' -H "Authorization: Bearer ${SMO_TOKEN_DATA}" \ + | jq --raw-output '.["extensions"]["profileData"]["admin_client_key"]') # If you do not want to set up the CA data, you can execute following command without the secure checking # kubectl config set-cluster ${CLUSTER_NAME} --server=${K8S_SERVER} --insecure-skip-tls-verify @@ -350,13 +279,12 @@ with SMO. kubectl get ns # check the command working with this context + Now you can use “kubectl”, which means you set up a successfully + Kubernetes client. But, it uses the default admin user, so I + recommend you create an account for yourself. - Now you can use “kubectl”, it means you set up successful of the - Kubernetes client. But, it use the default admin user, so I recommend - you create an account for yourself. - - Create a new user and account for K8S with “cluster-admin” role. And, - set the token of this user to the base environment. + Create a new user and account for K8S with a “cluster-admin” role. + And, set the token of this user to the base environment. .. code:: bash diff --git a/o2ims/views/alarm_route.py b/o2ims/views/alarm_route.py index 4ca44ca..4f0b15c 100644 --- a/o2ims/views/alarm_route.py +++ b/o2ims/views/alarm_route.py @@ -36,6 +36,7 @@ def configure_api_route(): # ---------- API versions ---------- # @api_monitoring_v1.route("/v1/api_versions") class VersionRouter(Resource): + @api_monitoring_v1.doc('Get Monitoring API version') def get(self): return { 'uriPrefix': request.base_url.rsplit('/', 1)[0], @@ -82,6 +83,7 @@ class AlarmListRouter(Resource): model = AlarmDTO.alarm_event_record_get + @api_monitoring_v1.doc('Get Alarm Event Record List') @api_monitoring_v1.marshal_list_with(model) def get(self): parser = reqparse.RequestParser() @@ -125,7 +127,7 @@ class AlarmGetRouter(Resource): model = AlarmDTO.alarm_event_record_get - @api_monitoring_v1.doc('Get AlarmEventRecord') + @api_monitoring_v1.doc('Get Alarm Event Record Information') @api_monitoring_v1.marshal_with(model) def get(self, alarmEventRecordId): result = alarm_view.alarm_event_record_one(alarmEventRecordId, bus.uow) @@ -142,7 +144,7 @@ class SubscriptionsListRouter(Resource): model = SubscriptionDTO.subscription_get expect = SubscriptionDTO.subscription_create - @api_monitoring_v1.doc('List alarm subscriptions') + @api_monitoring_v1.doc('Get Alarm Subscription List') @api_monitoring_v1.marshal_list_with(model) @api_monitoring_v1.param( PAGE_PARAM, @@ -186,7 +188,7 @@ class SubscriptionsListRouter(Resource): ret = alarm_view.subscriptions(bus.uow, **kwargs) return link_header(request.full_path, ret) - @api_monitoring_v1.doc('Create a alarm subscription') + @api_monitoring_v1.doc('Create a Alarm Subscription') @api_monitoring_v1.expect(expect) @api_monitoring_v1.marshal_with( model, code=201, @@ -208,7 +210,7 @@ class SubscriptionGetDelRouter(Resource): model = SubscriptionDTO.subscription_get - @api_monitoring_v1.doc('Get Alarm Subscription by ID') + @api_monitoring_v1.doc('Get Alarm Subscription Information') @api_monitoring_v1.marshal_with(model) @api_monitoring_v1.param( 'all_fields', @@ -239,7 +241,7 @@ class SubscriptionGetDelRouter(Resource): raise NotFoundException( "Subscription {} doesn't exist".format(alarmSubscriptionID)) - @api_monitoring_v1.doc('Delete subscription by ID') + @api_monitoring_v1.doc('Delete an Alarm Subscription') @api_monitoring_v1.response(200, 'Subscription deleted') def delete(self, alarmSubscriptionID): result = alarm_view.subscription_delete(alarmSubscriptionID, bus.uow) diff --git a/o2ims/views/api_ns.py b/o2ims/views/api_ns.py index 0ee29c4..e1fad44 100644 --- a/o2ims/views/api_ns.py +++ b/o2ims/views/api_ns.py @@ -33,6 +33,7 @@ api_ims_monitoring = O2Namespace( @api_ims_inventory.route('/api_versions') class InventoryVersion(Resource): + @api_ims_inventory.doc('Get Inventory Version') def get(self): return { 'uriPrefix': request.base_url.rsplit('/', 1)[0], @@ -46,6 +47,7 @@ class InventoryVersion(Resource): @api_ims_monitoring.route('/api_versions') class MonitoringVersion(Resource): + @api_ims_monitoring.doc('Get Monitoring Version') def get(self): return { 'uriPrefix': request.base_url.rsplit('/', 1)[0], diff --git a/o2ims/views/ocloud_route.py b/o2ims/views/ocloud_route.py index 75d0df6..8b0ccf5 100644 --- a/o2ims/views/ocloud_route.py +++ b/o2ims/views/ocloud_route.py @@ -38,6 +38,7 @@ def configure_api_route(): # ---------- API versions ---------- # @api_ims_inventory_v1.route("/v1/api_versions") class VersionRouter(Resource): + @api_ims_inventory_v1.doc('Get Inventory API version') def get(self): return { 'uriPrefix': request.base_url.rsplit('/', 1)[0], @@ -79,6 +80,7 @@ class OcloudsListRouter(Resource): ocloud_get = OcloudDTO.ocloud + @api_ims_inventory_v1.doc('Get Ocloud Information') @api_ims_inventory_v1.marshal_with(ocloud_get) def get(self): res = ocloud_view.oclouds(bus.uow) @@ -121,6 +123,7 @@ class ResourceTypesListRouter(Resource): model = ResourceTypeDTO.resource_type_get + @api_ims_inventory_v1.doc('Get Resource Type List') @api_ims_inventory_v1.marshal_list_with(model) def get(self): parser = reqparse.RequestParser() @@ -163,7 +166,7 @@ class ResourceTypeGetRouter(Resource): model = ResourceTypeDTO.resource_type_get - @api_ims_inventory_v1.doc('Get resource type') + @api_ims_inventory_v1.doc('Get Resource Type Information') @api_ims_inventory_v1.marshal_with(model) def get(self, resourceTypeID): result = ocloud_view.resource_type_one(resourceTypeID, bus.uow) @@ -207,6 +210,7 @@ class ResourcePoolsListRouter(Resource): model = ResourcePoolDTO.resource_pool_get + @api_ims_inventory_v1.doc('Get Resource Pool List') @api_ims_inventory_v1.marshal_list_with(model) def get(self): parser = reqparse.RequestParser() @@ -249,7 +253,7 @@ class ResourcePoolGetRouter(Resource): model = ResourcePoolDTO.resource_pool_get - @api_ims_inventory_v1.doc('Get resource pool') + @api_ims_inventory_v1.doc('Get Resource Pool Information') @api_ims_inventory_v1.marshal_with(model) def get(self, resourcePoolID): result = ocloud_view.resource_pool_one(resourcePoolID, bus.uow) @@ -300,6 +304,7 @@ class ResourcesListRouter(Resource): model = ResourceDTO.resource_list + @api_ims_inventory_v1.doc('Get Resource List') @api_ims_inventory_v1.marshal_list_with(model) def get(self, resourcePoolID): parser = reqparse.RequestParser() @@ -351,7 +356,7 @@ class ResourceGetRouter(Resource): # model = dto.get_resource_get() model = ResourceDTO.recursive_resource_mapping() - @api_ims_inventory_v1.doc('Get resource') + @api_ims_inventory_v1.doc('Get Resource Information') @api_ims_inventory_v1.marshal_with(model) def get(self, resourcePoolID, resourceID): result = ocloud_view.resource_one(resourceID, bus.uow, resourcePoolID) @@ -395,6 +400,7 @@ class DeploymentManagersListRouter(Resource): model = DeploymentManagerDTO.deployment_manager_list + @api_ims_inventory_v1.doc('Get Deployment Manager List') @api_ims_inventory_v1.marshal_list_with(model) def get(self): parser = reqparse.RequestParser() @@ -441,7 +447,7 @@ class DeploymentManagerGetRouter(Resource): model = DeploymentManagerDTO.deployment_manager_get - @api_ims_inventory_v1.doc('Get deployment manager') + @api_ims_inventory_v1.doc('Get Deployment Manager Information') @api_ims_inventory_v1.marshal_with(model) def get(self, deploymentManagerID): parser = reqparse.RequestParser() @@ -470,7 +476,7 @@ class SubscriptionsListRouter(Resource): model = SubscriptionDTO.subscription_get expect = SubscriptionDTO.subscription_create - @api_ims_inventory_v1.doc('List subscriptions') + @api_ims_inventory_v1.doc('Get Subscription List') @api_ims_inventory_v1.marshal_list_with(model) @api_ims_inventory_v1.param( PAGE_PARAM, @@ -514,7 +520,7 @@ class SubscriptionsListRouter(Resource): ret = ocloud_view.subscriptions(bus.uow, **kwargs) return link_header(request.full_path, ret) - @api_ims_inventory_v1.doc('Create a subscription') + @api_ims_inventory_v1.doc('Create a Subscription') @api_ims_inventory_v1.expect(expect) @api_ims_inventory_v1.marshal_with( model, code=201, @@ -536,7 +542,7 @@ class SubscriptionGetDelRouter(Resource): model = SubscriptionDTO.subscription_get - @api_ims_inventory_v1.doc('Get subscription by ID') + @api_ims_inventory_v1.doc('Get Subscription Information') @api_ims_inventory_v1.marshal_with(model) @api_ims_inventory_v1.param( 'all_fields', @@ -567,7 +573,7 @@ class SubscriptionGetDelRouter(Resource): raise NotFoundException("Subscription {} doesn't exist".format( subscriptionID)) - @api_ims_inventory_v1.doc('Delete subscription by ID') + @api_ims_inventory_v1.doc('Delete a Subscription') @api_ims_inventory_v1.response(200, 'Subscription deleted') def delete(self, subscriptionID): result = ocloud_view.subscription_delete(subscriptionID, bus.uow) -- 2.16.6