From 90c9cbdd1002f381c5072cd967ba1ec91446f6c5 Mon Sep 17 00:00:00 2001 From: Alberto Losada Date: Fri, 15 Nov 2024 10:03:41 +0100 Subject: [PATCH] Re-structuring the documentation adding steps to deploy the o2ims as operator --- README.md | 756 +++++++++++++++++++++++++----------------------------- 1 file changed, 354 insertions(+), 402 deletions(-) diff --git a/README.md b/README.md index 92764c08..f9858fdb 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,46 @@ + +* [Operator Deployment](#operator-deployment) + * [Deploy the operator on your cluster](#deploy-the-operator-on-your-cluster) + * [Run](#run) +* [Local Deployment Start](#local-deployment-start) + * [Build binary](#build-binary) + * [Run](#run-1) + * [Metadata server](#metadata-server) + * [Deployment manager server](#deployment-manager-server) + * [Resource server](#resource-server) + * [Infrastructure Inventory Subscription Server (Resource Server)](#infrastructure-inventory-subscription-server-resource-server) + * [Alarm server](#alarm-server) + * [Alarm Subscription server](#alarm-subscription-server) + * [Alarm Notification server](#alarm-notification-server) +* [Testing API endpoints on a cluster](#testing-api-endpoints-on-a-cluster) +* [Registering the O2IMS application with the SMO](#registering-the-o2ims-application-with-the-smo) +* [Using the development debug mode to attach the DLV debugger](#using-the-development-debug-mode-to-attach-the-dlv-debugger) +* [Request Examples](#request-examples) + * [Query the Metadata server](#query-the-metadata-server) + * [GET api_versions](#get-api_versions) + * [GET O-Cloud infrastructure information](#get-o-cloud-infrastructure-information) + * [Query the Deployment manager server](#query-the-deployment-manager-server) + * [GET deploymentManagers List](#get-deploymentmanagers-list) + * [GET field or fields from the deploymentManagers List](#get-field-or-fields-from-the-deploymentmanagers-list) + * [GET deploymentManagers List using filter](#get-deploymentmanagers-list-using-filter) + * [Query the Resource server](#query-the-resource-server) + * [GET Resource Type List](#get-resource-type-list) + * [GET Specific Resource Type](#get-specific-resource-type) + * [GET Resource Pool List](#get-resource-pool-list) + * [GET Specific Resource Pool](#get-specific-resource-pool) + * [GET all Resources of a specific Resource Pool](#get-all-resources-of-a-specific-resource-pool) + * [Query the Infrastructure Inventory Subscription (Resource Server)](#query-the-infrastructure-inventory-subscription-resource-server) + * [GET Infrastructure Inventory Subscription List](#get-infrastructure-inventory-subscription-list) + * [GET Infrastructure Inventory Subscription Information](#get-infrastructure-inventory-subscription-information) + * [POST a new Infrastructure Inventory Subscription Information](#post-a-new-infrastructure-inventory-subscription-information) + * [DELETE an Infrastructure Inventory Subscription](#delete-an-infrastructure-inventory-subscription) + + + + # O-RAN O2IMS This project is an implementation of the O-RAN O2 IMS API on top of @@ -8,284 +51,136 @@ so don't try to use it for anything close to a production environment. ***Note: this README is only for development purposes.*** - -* 1. [Operator Deployment](#OperatorDeployment) - * 1.1. [Deploy the operator on your cluster](#Deploytheoperatoronyourcluster) - * 1.2. [Run](#Run) - * 1.2.1. [Metadata server](#Metadataserver) - * 1.2.2. [Deployment manager server](#Deploymentmanagerserver) - * 1.2.3. [Resource server](#Resourceserver) -* 2. [Local Deployment Start](#LocalDeploymentStart) - * 2.1. [Build binary](#Buildbinary) - * 2.2. [Run](#Run-1) - * 2.2.1. [Metadata server](#Metadataserver-1) - * 2.2.2. [Deployment manager server](#Deploymentmanagerserver-1) - * 2.2.3. [Resource server](#Resourceserver-1) - * 2.2.4. [Infrastructure Inventory Subscription Server (Resource Server)](#InfrastructureInventorySubscriptionServerResourceServer) - * 2.2.5. [Alarm server](#Alarmserver) - * 2.2.6. [Alarm Subscription server](#AlarmSubscriptionserver) - * 2.2.7. [Alarm Notification server](#AlarmNotificationserver) - - - - -## 1. Operator Deployment +## Operator Deployment The ORAN O2 IMS implementation in OpenShift is managed by the IMS operator. It configures the different components defined in the specification: -the deployment managers service, the resource server, alert server, subscriptions to resource and alert. +the deployment manager service, the resource server, alarm server, subscriptions to resource and alert. The IMS operator will create an O-Cloud API that will be available to be queried, for instance from a SMO. It also provides a configuration mechanism using a Kubernetes custom resource definition (CRD) that allows the hub cluster administrator to configure the different IMS microservices properly. -### 1.1. Deploy the operator on your cluster +### Deploy the operator on your cluster -The IMS operator is installed on an OpenShift cluster where Red Hat Advanced Cluster Management for Kubernetes (RHACM), a.k.a. hub cluster, is installed too. -Be sure you are connected to your hub cluster and run: - -``` bash -make deploy -``` -The operator then is installed in the `oran-o2ims-system` namespace. - -```bash -$ oc get pods -n oran-o2ims-system -NAME READY STATUS RESTARTS AGE -oran-o2ims-controller-manager-8668794cdc-27xvf 2/2 Running 0 11s -``` +The IMS operator is installed on an OpenShift cluster where Red Hat Advanced Cluster Management for Kubernetes (RHACM), a.k.a. hub cluster, is installed too. Let’s install the operator. You can use the latest automatic build from the [openshift-kni namespace](https://quay.io/repository/openshift-kni/oran-o2ims-operator) in quay.io or build your container image with the latest code. -### 1.2. Run +If you want to build the image yourself and push it to your registry right after: -The ORAN2IMS custom resource is the way to configure the different components of the IMS operator. -Notice that the ORAN2IMS object must be placed in one of the [allowed namespaces](https://www.google.com/url?q=https://github.com/openshift-kni/oran-o2ims/blob/main/internal/cmd/operator/start_controller_manager.go%23L127&sa=D&source=docs&ust=1722264090981796&usg=AOvVaw1mnJq0RKXe-dd1os-EfDBP), such as the oran-o2ims. -Let’s configure the Metadata server. +> :warning: Replace the IMAGE_NAME value with the full name of your container image ```bash -$ oc create ns oran-o2ims +$ export IMAGE_NAME=quay.io/alosadag/oran-o2ims:v4.16 +$ git clone https://github.com/openshift-kni/oran-o2ims.git +$ cd oran-o2ims +$ make docker-build docker-push CONTAINER_TOOL=podman IMG=${IMAGE_NAME} + +..REDACTED.. +Update dependencies +hack/update_deps.sh +hack/install_test_deps.sh +Downloading golangci-lint +… +[3/3] STEP 5/5: ENTRYPOINT ["/usr/bin/oran-o2ims"] +[3/3] COMMIT quay.io/alosadag/oran-o2ims:v4.16 +--> eaa55268bfff +Successfully tagged quay.io/alosadag/oran-o2ims:v4.16 +eaa55268bfffeb23644c545b3d0a768326821e0afea8b146c51835b3f90a9d0c +``` + +Now, let's deploy the operator. If you want to deploy your already built image then add the `IMG=${IMAGE_NAME}` argument to the `make` command: + +```sh +$ make deploy install + +… REDACTED … +Update dependencies +hack/update_deps.sh +hack/install_test_deps.sh +Downloading golangci-lint +… REDACTED … +/home/alosadag/Documents/CNF/ORAN/oran-o2ims/bin/kustomize build config/default | /home/alosadag/Documents/CNF/ORAN/oran-o2ims/bin/kubectl apply -f - namespace/oran-o2ims created +serviceaccount/oran-o2ims-controller-manager created +role.rbac.authorization.k8s.io/oran-o2ims-leader-election-role created +clusterrole.rbac.authorization.k8s.io/oran-o2ims-manager-role created +clusterrole.rbac.authorization.k8s.io/oran-o2ims-metrics-reader created +clusterrole.rbac.authorization.k8s.io/oran-o2ims-proxy-role created +rolebinding.rbac.authorization.k8s.io/oran-o2ims-leader-election-rolebinding created +clusterrolebinding.rbac.authorization.k8s.io/oran-o2ims-manager-rolebinding created +clusterrolebinding.rbac.authorization.k8s.io/oran-o2ims-proxy-rolebinding created +configmap/oran-o2ims-env-config created +service/oran-o2ims-controller-manager-metrics-service created +deployment.apps/oran-o2ims-controller-manager created ``` -#### 1.2.1. Metadata server - -The metadata server returns information about the supported versions of the -API. It doesn't require any backend, only the O-Cloud identifier (`cloudID`) and the route where the Metadata -server is available (`ingressHost`). - -You can start by creating the ORANO2IMS custom resource in a yaml file: - -```yaml -apiVersion: oran.openshift.io/v1alpha1 -kind: ORANO2IMS -metadata: - annotations: - labels: - app.kubernetes.io/created-by: oran-o2ims - app.kubernetes.io/instance: orano2ims-sample - app.kubernetes.io/managed-by: kustomize - app.kubernetes.io/name: orano2ims - app.kubernetes.io/part-of: oran-o2ims - name: sample - namespace: oran-o2ims -spec: - alarmSubscriptionServerConfig: - enabled: false - cloudId: c0332915-6bff-4d8d-8628-0ab3cc2c7e5e #your cloudID - deploymentManagerServerConfig: - enabled: false - image: quay.io/openshift-kni/oran-o2ims:4.16 - ingressHost: oran-o2ims.apps.hub0.inbound-int.se-lab.eng.rdu2.dc.redhat.com #your ingress URI - metadataServerConfig: - enabled: true - resourceServerConfig: - enabled: false -``` - -And apply it to the hub cluster. +The operator and the default enabled components are installed in the `oran-o2ims` namespace, which is created during the install. ```bash -$ oc apply -f sample-oran2ims-metadata.yaml  -orano2ims.oran.openshift.io/sample created -``` - -Then, a metadata-server Pod is running on the oran-o2ims namespace and a route created with the value included in the previous custom resource, -specifically in the spec.ingressHost field. That’s the URI where the IMS API will be listening from outside the OpenShift cluster: - -```bash -$ oc get pods -n oran-o2ims -NAME                              READY   STATUS    RESTARTS   AGE -metadata-server-c655b559b-6chmx   1/1     Running   0          12s - -$ oc get route -n oran-o2ims -NAME        HOST/PORT                                                        PATH                                                   SERVICES                    PORT   TERMINATION          WILDCARD -api-27qrj   oran-o2ims.apps.hub0.inbound-int.se-lab.eng.rdu2.dc.redhat.com   /                                                      metadata-server             api    reencrypt/Redirect   None -``` - -Before querying the Metadata Server we need to allow that request. -Therefore we need to create a token associated with an already created serviceAccount named `client`: +$ oc get pods -n oran-o2ims-system +NAME READY STATUS RESTARTS AGE +oran-o2ims-controller-manager-8668794cdc-27xvf 2/2 Running 0 9m15s +deployment-manager-server-565f5cc68d-gwhmh 2/2 Running 0 8m50s +metadata-server-7f4f8f87fb-zc7s8 2/2 Running 0 8m50s +resource-server-8668dffd44-xn9pj 2/2 Running 0 8m50s -```bash -$ export CLIENT_TOKEN=$(oc create token -n oran-o2ims client --duration=24h) -$ export API_URI=$(oc -n oran-o2ims get route -o jsonpath={.items[0].spec.host}) ``` +Several routes were created in the same namespace too. The `HOST` column is the URI where the o2ims API will be listening from outside the OpenShift cluster, for instance where the SMO will connect to. -##### Requests Examples - -###### GET API version - -To obtain the API version deployed: - -```bash -$ curl --insecure --silent --header "Authorization: Bearer $CLIENT_TOKEN" -"https://${API_URI}/o2ims-infrastructureInventory/v1/api_versions" | jq +```sh +$ oc get route -n oran-o2ims +NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD +api-2fv99 o2ims.apps.hub0.inbound-int.se-lab.eng.rdu2.dc.redhat.com / metadata-server api reencrypt/Redirect None +api-cbvbz o2ims.apps.hub0.inbound-int.se-lab.eng.rdu2.dc.redhat.com /o2ims-infrastructureInventory/v1/resourceTypes resource-server api reencrypt/Redirect None +api-v92jb o2ims.apps.hub0.inbound-int.se-lab.eng.rdu2.dc.redhat.com /o2ims-infrastructureInventory/v1/deploymentManagers deployment-manager-server api reencrypt/Redirect None +api-xllml o2ims.apps.hub0.inbound-int.se-lab.eng.rdu2.dc.redhat.com /o2ims-infrastructureInventory/v1/resourcePools resource-server api reencrypt/Redirect None ``` -###### GET O-Cloud information - -The next query obtains O-Cloud information: +The operator by default creates a default inventory CR in the oran-o2ims namespace: ```bash -$ curl --insecure --silent --header "Authorization: Bearer $CLIENT_TOKEN" -"https://${API_URI}/o2ims-infrastructureInventory/v1" | jq +$ oc get inventory -n oran-o2ims +NAME AGE +default 4m20s ``` -#### 1.2.2. Deployment manager server - -The deployment manager server needs to connect to kubernetes API of the -RHACM hub. If you are already connected to an OpenShift cluster that has -RHACM installed and configured you can obtain the token like this: +> :warning: Currently, the following components are enabled by default. +```sh +$ oc get inventory -n oran-o2ims -oyaml ``` -$ export BACKEND_TOKEN=$(oc create token -n open-cluster-management multicluster-operators --duration=24h) -``` -Next, enable and configure the `deploymentManagerServerConfig` section of the ORANO2IMS CR yaml file. - ```yaml -apiVersion: oran.openshift.io/v1alpha1 -kind: ORANO2IMS +apiVersion: o2ims.oran.openshift.io/v1alpha1 +kind: Inventory metadata: - annotations: - labels: - app.kubernetes.io/created-by: oran-o2ims - app.kubernetes.io/instance: orano2ims-sample - app.kubernetes.io/managed-by: kustomize - app.kubernetes.io/name: orano2ims - app.kubernetes.io/part-of: oran-o2ims - name: sample + creationTimestamp: "2024-11-07T09:26:12Z" + generation: 1 + name: default namespace: oran-o2ims + resourceVersion: "279507769" + uid: aeb85580-f7ca-4861-8c38-3f57902b1617 spec: alarmSubscriptionServerConfig: enabled: false - cloudId: c0332915-6bff-4d8d-8628-0ab3cc2c7e5e deploymentManagerServerConfig: - backendToken: ${BACKEND_TOKEN} backendType: regular-hub enabled: true - image: quay.io/openshift-kni/oran-o2ims:4.16.0 - ingressHost: oran-o2ims.apps.hub0.inbound-int.se-lab.eng.rdu2.dc.redhat.com metadataServerConfig: enabled: true resourceServerConfig: - enabled: false -``` -Next, apply the sample ORANO2IMS custom resource with the new configuration. - -```bash -$ oc apply -f sample-oran2ims-dms.yaml -orano2ims.oran.openshift.io/sample configured -``` - -See that a new Pod started in the oran-o2ims namespace. - -```bash -$ oc get pods -n oran-o2ims -NAME                                         READY   STATUS    RESTARTS   AGE -deployment-manager-server-785997bd4b-r8qbt   1/1     Running   0          3s -metadata-server-c655b559b-tf7f7              1/1     Running   0          13h -``` - -Check that the Pod started successfully, you can see the output of the Pod to look for errors or check the status of the ORAN2IMS custom resource: - -```bash -$ oc get orano2imses.oran.openshift.io sample -ojsonpath={.status.deploymentStatus} | jq -{ - "conditions": [ - { - "lastTransitionTime": "2024-07-24T07:02:48Z", - "message": "Deployment has minimum availability.", - "reason": "MinimumReplicasAvailable", - "status": "True", - "type": "MetadataServerAvailable" - }, - { - "lastTransitionTime": "2024-07-24T07:17:48Z", - "message": "Deployment has minimum availability.", - "reason": "MinimumReplicasAvailable", - "status": "True", - "type": "DeploymentServerAvailable" - } - ] -} -``` - -##### Requests Examples - -###### GET deploymentManagers List - -To get a list of deploymentManagers: - -```bash -$ curl --insecure --silent --header "Authorization: Bearer $CLIENT_TOKEN" -"https://${API_URI}/o2ims-infrastructureInventory/v1/deploymentManagers" | jq -``` - -###### GET fields from the deploymentManagers List - -To get only the name of the available deploymentManagers: - -```bash -$ curl --insecure --silent --header "Authorization: Bearer $CLIENT_TOKEN" -"https://${API_URI}/o2ims-infrastructureInventory/v1/deploymentManagers?fields=name" | jq -``` - -###### GET deploymentManagers List using filter - -To get the deploymentManagers whose name is **not** local-cluster. - -```bash -$ curl --insecure --silent --header "Authorization: Bearer $CLIENT_TOKEN" -"https://${API_URI}/o2ims-infrastructureInventory/v1/deploymentManagers?filter=(neq,name,local-cluster)" | jq - | jq + enabled: true ``` -#### 1.2.3. Resource server - -The resource server exposes endpoints for retrieving resource types, resource pools -and resources objects. The server relies on the Search Query API of ACM hub. -Follow these [instructions](docs/dev/env_acm.md#search-query-api) to enable -and configure the search API access. The resource server will translate those REST requests and send them to the ACM search server that implements a graphQL API. - -The required URL and token can be obtained as follows: +### Run -```bash -$ export BACKEND_URL=$( - oc get route -n open-cluster-management search-api -o json | - jq -r '"https://" + .spec.host' -) -$ export BACKEND_TOKEN_RS=$( - oc create token oauth-apiserver-sa -n openshift-oauth-apiserver --duration=48h - ) -``` +The `Inventory` custom resource (CR) is the way to configure the different components of the IMS operator. The default Inventory CR that is created by the system is sufficient to enable the basic API functionality. -Next, configure the `resourceServerConfig` section of the ORANO2IMS CR: +The end user must edit the default Inventory CR to enable communication with the SMO instance after the SMO has been configured to accept connections from this O-Cloud. Specifically, the `cloudID` and `smo` attributes will need to be configured appropriately. The `cloudID` is the globally unique UUID value assigned to this O-Cloud by the SMO. ```yaml -apiVersion: oran.openshift.io/v1alpha1 -kind: ORANO2IMS +apiVersion: o2ims.oran.openshift.io/v1alpha1 +kind: Inventory metadata: annotations: labels: @@ -294,111 +189,84 @@ metadata: app.kubernetes.io/managed-by: kustomize app.kubernetes.io/name: orano2ims app.kubernetes.io/part-of: oran-o2ims - name: sample + name: default namespace: oran-o2ims -spec: +spec: + smo: + url: http://smo.example.com + registrationEndpoint: /mock_smo/v1/ocloud_observer + #image: quay.io/NAMESPACE/CONTAINER_IMAGE // uncomment if you want to use your built image otherwise will be populated with the default image. + #alarmSubscription is not yet available, enable it otherwise. alarmSubscriptionServerConfig: - enabled: false - cloudId: c0332915-6bff-4d8d-8628-0ab3cc2c7e5e + enabled: false + cloudID: f7fd171f-57b5-4a17-b176-9a73bf6064a4 deploymentManagerServerConfig: - backendToken: ${BACKEND_TOKEN} - backendType: regular-hub enabled: true - image: quay.io/openshift-kni/oran-o2ims:4.16.0 - ingressHost: oran-o2ims.apps.hub0.inbound-int.se-lab.eng.rdu2.dc.redhat.com + #examples of using the extensions spec metadataServerConfig: enabled: true resourceServerConfig: - backendToken: ${BACKEND_TOKEN_RS} - backendURL: https://${BACKEND_URL} + # A route must be created in the open-cluster-management namespace (RHACM) to expose the search collector Pod + backendURL: https://search-api-open-cluster-management.apps.hub0.inbound-int.se-lab.eng.rdu2.dc.redhat.com enabled: true ``` -Apply the configuration: - -```bash -$ oc apply -f sample-oran2ims-resource.yaml -orano2ims.oran.openshift.io/sample configured -``` - -Validate a new Pod is running in the oran-o2ims namespace: - -```bash -$ oc get pods -NAME READY STATUS RESTARTS AGE -deployment-manager-server-7488685b78-5wjmh 1/1 Running 0 67m -metadata-server-c655b559b-57x9w 1/1 Running 0 85m -resource-server-846b96545-4f5sj 1/1 Running 0 116s -``` - -Check that the Pod started successfully, you can see the output of the Pod to look for errors or check the status of the ORAN2IMS custom resource: - -```bash -$ oc get orano2imses.oran.openshift.io sample -ojsonpath={.status.deploymentStatus} | jq -{ - "conditions": [ - { - "lastTransitionTime": "2024-07-24T07:02:48Z", - "message": "Deployment has minimum availability.", - "reason": "MinimumReplicasAvailable", - "status": "True", - "type": "MetadataServerAvailable" - }, - { - "lastTransitionTime": "2024-07-24T07:17:48Z", - "message": "Deployment has minimum availability.", - "reason": "MinimumReplicasAvailable", - "status": "True", - "type": "DeploymentServerAvailable" - }, - { - "lastTransitionTime": "2024-07-24T08:22:49Z", - "message": "Deployment has minimum availability.", - "reason": "MinimumReplicasAvailable", - "status": "True", - "type": "ResourceServerAvailable" - } - ] -} -``` - -##### Requests Examples - -###### GET Resource Type List - -To get a list of resource types: - -```bash -$ curl -ks --header "Authorization: Bearer $CLIENT_TOKEN" "https://${API_URI}/o2ims-infrastructureInventory/v1/resourceTypes" | jq -``` - -###### GET Resource Pool List - -To get a list of resource pools: - -```bash -$ curl -ks --header "Authorization: Bearer $CLIENT_TOKEN" "https://${API_URI}/o2ims-infrastructureInventory/v1/resourcePools" | jq -``` - -###### GET Resource List -To get a list of resources in a resource pool: +Apply the patch to the hub cluster: ```bash -$ curl -ks --header "Authorization: Bearer $CLIENT_TOKEN" "https://${API_URI}/o2ims-infrastructureInventory/v1/resourcePools/{resourcePoolId} -/resources" | jq -``` - - -## 2. Local Deployment Start - -### 2.1. Build binary +$ oc apply -f inventory_sample.yaml +inventory.o2ims.oran.openshift.io/default configured +``` +The status of the different components of the O2IMS operator can be checked by examining the `status` field of the inventory CR. + +```sh +$ oc get inventory default -ojson | jq .status.deploymentStatus.conditions +``` +```json +[ + { + "lastTransitionTime": "2024-11-14T11:29:02Z", + "message": "Registered with SMO at: http://smo.example.com", + "reason": "SmoRegistrationSuccessful", + "status": "True", + "type": "SmoRegistrationCompleted" + }, + { + "lastTransitionTime": "2024-11-14T11:29:02Z", + "message": "Deployment has minimum availability.", + "reason": "MinimumReplicasAvailable", + "status": "True", + "type": "MetadataServerAvailable" + }, + { + "lastTransitionTime": "2024-11-14T11:29:02Z", + "message": "Deployment has minimum availability.", + "reason": "MinimumReplicasAvailable", + "status": "True", + "type": "ResourceServerAvailable" + }, + { + "lastTransitionTime": "2024-11-14T11:29:02Z", + "message": "Deployment has minimum availability.", + "reason": "MinimumReplicasAvailable", + "status": "True", + "type": "DeploymentServerAvailable" + } +] +``` +Also, you can check the logs of the Pods running in the `oran-o2ims` namespace searching for any error. + + +## Local Deployment Start + +### Build binary ``` bash make binary ``` -### 2.2. Run +### Run -#### 2.2.1. Metadata server +#### Metadata server The metadata server returns information about the supported versions of the API. It doesn't require any backend, only the O-Cloud identifier. You can start @@ -424,7 +292,7 @@ $ curl -s http://localhost:8000/o2ims-infrastructureInventory/v1 | jq Inside _VS Code_ use the _Run and Debug_ option with the `start metadata-server` [configuration](.vscode/launch.json). -#### 2.2.2. Deployment manager server +#### Deployment manager server The deployment manager server needs to connect to the non-kubernetes API of the ACM global hub. If you are already connected to an OpenShift cluster that has @@ -477,7 +345,7 @@ $ curl -s http://localhost:8001/o2ims-infrastructureInventory/v1/deploymentManag Inside _VS Code_ use the _Run and Debug_ option with the `start deployment-manager-server` [configuration](.vscode/launch.json). -#### 2.2.3. Resource server +#### Resource server The resource server exposes endpoints for retrieving resource types, resource pools and resources objects. The server relies on the Search Query API of ACM hub. @@ -526,31 +394,7 @@ $ ./oran-o2ims start resource-server --help Inside _VS Code_ use the _Run and Debug_ option with the `start resource-server` [configuration](.vscode/launch.json). -##### Requests Examples - -###### GET Resource Type List - -To get a list of resource types: -``` -$ curl -s http://localhost:8002/o2ims-infrastructureInventory/v1/resourceTypes | jq -``` - -###### GET Resource Pool List - -To get a list of resource pools: -``` -$ curl -s http://localhost:8002/o2ims-infrastructureInventory/v1/resourcePools | jq -``` - -###### GET Resource List - -To get a list of resources in a resource pool: -``` -$ curl -s http://localhost:8002/o2ims-infrastructureInventory/v1/resourcePools/{resourcePoolId} -/resources | jq -``` - -#### 2.2.4. Infrastructure Inventory Subscription Server (Resource Server) +#### Infrastructure Inventory Subscription Server (Resource Server) The infrastructure inventory subscription server exposes endpoints for creating, retrieving and deleting resource subscriptions. @@ -586,48 +430,7 @@ $ ./oran-o2ims start infrastructure-inventory-subscription-server --help Inside _VS Code_ use the _Run and Debug_ option with the `start infrastructure-inventory-subscription-server` [configuration](.vscode/launch.json). -##### Request Examples - -###### GET Infrastructure Inventory Subscription List - -To get a list of resource subscriptions: -``` -$ curl -s http://localhost:8004/o2ims-infrastructureInventory/v1/subscriptions | jq -``` - -###### GET Infrastructure Inventory Subscription Information - -To get all the information about an existing resource subscription: -``` -$ curl -s http://localhost:8004/o2ims-infrastructureInventory/v1/subscriptions/ | jq -``` - -###### POST a new Infrastructure Inventory Subscription Information - -To add a new resource subscription: -``` -$ curl -s -X POST \ ---header "Content-Type: application/json" \ --d @infra-sub.json http://127.0.0.1:8004/o2ims-infrastructureInventory/v1/subscriptions | jq -``` -Where the content of `infra-sub.json` is as follows: -``` -{ - "consumerSubscriptionId": "69253c4b-8398-4602-855d-783865f5f25c", - "filter": "(eq,extensions/country,US);", - "callback": "https://128.224.115.15:1081/smo/v1/o2ims_inventory_observer" -} -``` - -###### DELETE an Infrastructure Inventory Subscription - -To delete an existing resource subscription: -``` -$ curl -s -X DELETE \ -http://localhost:8000/o2ims-infrastructureInventory/v1/subscriptions/ | jq -``` - -#### 2.2.5. Alarm server +#### Alarm server The alarm server exposes endpoints for retrieving alarms (AlarmEventRecord objects). The server relies on the Alertmanager API from Observability operator. @@ -706,7 +509,7 @@ Notes: * The server supports the `alarmProbableCauses` endpoint for exposing a custom list of probable causes. * The list is available in [data folder](internal/files/alarms/probable_causes.json). Can be customized and maintained as required. -#### 2.2.6. Alarm Subscription server +#### Alarm Subscription server To use the configmap to persist the subscriptions, the namespace "orantest" should be created at hub cluster for now. @@ -754,7 +557,7 @@ Above example will post an alarm subscription defined in subscription.json file Inside _VS Code_ use the _Run and Debug_ option with the `start alarm-subscription-server` [configuration](.vscode/launch.json). -#### 2.2.7. Alarm Notification server +#### Alarm Notification server The alarm-notification-server should use together with alarm subscription server. The alarm subscription sever accept and manages the alarm subscriptions. The alarm notificaton servers synch the alarm subscriptions via perisist storage. To use the configmap to persist the subscriptions, the namespace "orantest" should be created at hub cluster for now (will use official oranims namespace in future). Alarm subscripton server and corresonding alarm notification server should have same namespace and configmap-name. The alarm notification server accept the alerts, match the subscription filter, build and send out the alarm notification based on url in the subscription. @@ -803,15 +606,32 @@ Inside _VS Code_ use the _Run and Debug_ option with the `start alarm-notification-server` [configuration](.vscode/launch.json). -## Testing API endpoints on a cluster +## Testing API endpoints on a cluster -**NOTE:** If you already have a user account from which you can generate an API access token then you can skip ahead to step +> :exclamation: If you already have a user account from which you can generate an API access token then you can skip ahead to step 3 assuming you have already stored your access token in a variable called `MY_TOKEN`. -1. Apply the test client service account CR instances. +1. Apply the test client service account CR instances. It will enable us to authenticate against the O2IMS API. It creates the proper cluster role (`oran-o2ims-test-client-role`) and bind it (`oran-o2ims-test-client-binding`) to the service account (`test-client`). ```shell $ oc apply -f config/testing/client-service-account-rbac.yaml +serviceaccount/test-client created +clusterrole.rbac.authorization.k8s.io/oran-o2ims-test-client-role created +clusterrolebinding.rbac.authorization.k8s.io/oran-o2ims-test-client-binding created +``` +Verify a new service account called test-client is created in the oran-o2ims namespace. + +```sh +$ oc get sa -n oran-o2ims +NAME SECRETS AGE +builder 0 117m +default 0 117m +deployer 0 117m +deployment-manager-server 0 16m +metadata-server 0 16m +oran-o2ims-controller-manager 0 117m +resource-server 0 16m +test-client 0 15m ``` 2. Generate a token to access the API endpoint @@ -821,6 +641,15 @@ $ MY_SECRET_NAME=$(oc get sa -n oran-o2ims test-client -ojsonpath='{.secrets[0]. $ MY_TOKEN=$(oc get secret -n oran-o2ims ${MY_SECRET_NAME} -ojsonpath='{.metadata.annotations.openshift\.io/token-secret\.value}') ``` +Export the token in a variable such as MY_TOKEN and adjust the duration of the token to your needs. + +```sh +$ export MY_TOKEN=$(oc create token -n oran-o2ims test-client --duration=24h) +``` + +That token will be used as an authorization bearer in our queries sent from the SMO or any other object outside OpenShift: + + 3. Access an API endpoint ```shell @@ -829,7 +658,7 @@ curl -kq https://o2ims.apps.${MY_CLUSTER}/o2ims-infrastructureInventory/v1/api_v -H "Authorization: Bearer ${MY_TOKEN}" ``` -## Registering the O2IMS application with the SMO +## Registering the O2IMS application with the SMO Once the hub cluster is setup and the O2IMS application is started the end user must update the Inventory CR to configure the SMO attributes so that the application can register with the SMO. In a production environment this @@ -909,7 +738,7 @@ Status: ... ``` -## Using the development debug mode to attach the DLV debugger +## Using the development debug mode to attach the DLV debugger The following instructions provide a mechanism to build an image that is based on a more full-featured distro so that debug tools are available in the image. It also tailors the deployment configuration so that certain features are @@ -945,11 +774,135 @@ dlv attach --continue --accept-multiclient --api-version 2 --headless --listen : 5. Use your IDE's debug capabilities to attach to `localhost:40000` to start your debug session. This will vary based on which IDE is being used. -## Request Examples +## Request Examples + +### Query the Metadata server -### Infrastructure Inventory Subscription (Resource Server) +> :warning: Double check you already applied the proper permissions to access the O2IMS API and created the test-client service account. See section [Testing API endpoints on a cluster](#testing-API-endpoints-on-a-cluster) -#### GET Infrastructure Inventory Subscription List + +Notice the `API_URI` is the route HOST/PORT column of the oran-o2ims operator. + +```sh +$ oc get routes -n oran-o2ims +NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD +api-2fv99 o2ims.apps.hub0.inbound-int.se-lab.eng.rdu2.dc.redhat.com / metadata-server api reencrypt/Redirect None +api-cbvbz o2ims.apps.hub0.inbound-int.se-lab.eng.rdu2.dc.redhat.com /o2ims-infrastructureInventory/v1/resourceTypes resource-server api reencrypt/Redirect None +api-v92jb o2ims.apps.hub0.inbound-int.se-lab.eng.rdu2.dc.redhat.com /o2ims-infrastructureInventory/v1/deploymentManagers deployment-manager-server api reencrypt/Redirect None +api-xllml o2ims.apps.hub0.inbound-int.se-lab.eng.rdu2.dc.redhat.com /o2ims-infrastructureInventory/v1/resourcePools resource-server api reencrypt/Redirect None +``` + +Export the o2ims endpoint as the API_URI variable so it can be re-used in the requests. + +```sh +export API_URI=o2ims.apps.${DOMAIN} +``` + +#### GET api_versions + +To get the api versions supported + +```sh +$ curl --insecure --silent --header "Authorization: Bearer $MY_TOKEN" +"https://${API_URI}/o2ims-infrastructureInventory/v1/api_versions" | jq +``` + +#### GET O-Cloud infrastructure information + +To obtain information from the O-Cloud:  + +```bash +$ curl --insecure --silent --header "Authorization: Bearer $MY_TOKEN" +"https://${API_URI}/o2ims-infrastructureInventory/v1" +``` + +### Query the Deployment manager server + +The deployment manager server (DMS) needs to connect to kubernetes API of the RHACM hub to obtain the required information. Here we can see a couple of queries to the DMS. + +#### GET deploymentManagers List + +To get a list of all the deploymentManagers (clusters) available in our O-Cloud: + +```bash +$ curl --insecure --silent --header "Authorization: Bearer $MY_TOKEN" +"https://${API_URI}/o2ims-infrastructureInventory/v1/deploymentManagers" | jq +``` + +#### GET field or fields from the deploymentManagers List + +To get a list of only the `name` of the available deploymentManagers available in our O-Cloud: + +```bash +$ curl --insecure --silent --header "Authorization: Bearer $MY_TOKEN" +"https://${API_URI}/o2ims-infrastructureInventory/v1/deploymentManagers?fields=name" | jq +``` + +#### GET deploymentManagers List using filter + +To get a list of all the deploymentManagers whose name is **not** local-cluster in our O-Cloud: + +```bash +$ curl --insecure --silent --header "Authorization: Bearer $MY_TOKEN" +"https://${API_URI}/o2ims-infrastructureInventory/v1/deploymentManagers?filter=(neq,name,local-cluster)" | jq + | jq +``` + +### Query the Resource server + +The resource server exposes endpoints for retrieving resource types, resource pools and resources objects. The server relies on the Search Query API of ACM hub. Follow these [instructions](docs/dev/env_acm.md#search-query-api) to enable +and configure the search API access. The resource server will translate those REST requests and send them to the ACM search server that implements a graphQL API. + +> :exclamation: To obtain the requested information we need to enable the searchCollector of all the managed clusters, concretely, in the KlusterletAddonConfig CR. + +#### GET Resource Type List + +To get a list of available resource types: + +```bash +$ curl -ks --header "Authorization: Bearer $MY_TOKEN" +"https://${API_URI}/o2ims-infrastructureInventory/v1/resourceTypes" | jq +``` +#### GET Specific Resource Type + +To get information of a specific resource type: + +```bash +$ curl -ks --header "Authorization: Bearer $MY_TOKEN" +"https://${API_URI}/o2ims-infrastructureInventory/v1/resourceTypes/${resource_type_name} | jq +``` + +#### GET Resource Pool List + +To get a list of available resource pools: + +```bash +$ curl -ks --header "Authorization: Bearer $MY_TOKEN" +"https://${API_URI}/o2ims-infrastructureInventory/v1/resourcePools" | jq +``` + +#### GET Specific Resource Pool + +To get information of a specific resource pool: + +```bash +$ curl -ks --header "Authorization: Bearer $MY_TOKEN" +"https://${API_URI}/o2ims-infrastructureInventory/v1/resourcePools/{resourcePoolId}" | jq +``` + +#### GET all Resources of a specific Resource Pool + +We can filter down to get all the resources of a specific resourcePool. + +```bash +$ curl -ks --header "Authorization: Bearer $MY_TOKEN" +"https://${API_URI}/o2ims-infrastructureInventory/v1/resourcePools/{resourcePoolId} +/resources" | jq +``` + +### Query the Infrastructure Inventory Subscription (Resource Server) + +#### GET Infrastructure Inventory Subscription List To get a list of resource subscriptions: @@ -957,7 +910,7 @@ To get a list of resource subscriptions: $ curl -s http://localhost:8004/o2ims-infrastructureInventory/v1/subscriptions | jq ``` -#### GET Infrastructure Inventory Subscription Information +#### GET Infrastructure Inventory Subscription Information To get all the information about an existing resource subscription: @@ -965,7 +918,7 @@ To get all the information about an existing resource subscription: $ curl -s http://localhost:8004/o2ims-infrastructureInventory/v1/subscriptions/ | jq ``` -#### POST a new Infrastructure Inventory Subscription Information +#### POST a new Infrastructure Inventory Subscription Information To add a new resource subscription: @@ -985,12 +938,11 @@ Where the content of `infra-sub.json` is as follows: } ``` -#### DELETE an Infrastructure Inventory Subscription +#### DELETE an Infrastructure Inventory Subscription To delete an existing resource subscription: ``` $ curl -s -X DELETE \ http://localhost:8004/o2ims-infrastructureInventory/v1/subscriptions/ | jq -``` - +``` \ No newline at end of file